Add documentation for breaking change

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 Here you can find upgrade changes in between releases and upgrade instructions.
 
+## [UNRELEASED]
+
+#### Breaking changes
+
+- **`singleuser.cmd` does not default to `jupyterhub-singleuser` - [#2138](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/pull/2138)**
+
+  Previous versions of Z2JH ignored the command (`CMD`) configured in the singleuser image by default.
+  This is no longer the case, when a singleuser pod is started the `CMD` from the container image will be used.
+  If you want to revert to the previous behaviour set `singleuser.cmd=jupyterhub-singleuser`.
+
+  This change was made to make it easier to support custom startup scripts such as those used in [`docker-stacks`](https://github.com/jupyter/docker-stacks),
+  as well as alternatives to jupyter-notebook including [Jupyterlab](https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html) and other applications based on [jupyter-server](https://jupyter-server.readthedocs.io/).
+
 ## [0.11]
 
 ### [0.11.1] - 2021-01-15

doc/source/jupyterhub/customizing/user-environment.md

@@ -69,6 +69,19 @@ If you'd like users to select an environment from **multiple docker images**,
 see {ref}`multiple-profiles`.
 ```
 
+The Docker image will be started with the [`ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) and [`CMD`](https://docs.docker.com/engine/reference/builder/#cmd) defined in the image.
+You can override `CMD`, by setting `singleuser.cmd`.
+
+```{note}
+In versions of Z2JH prior to 1.0.0 the images default was overridden.
+To restore this behaviour:
+```
+
+```yaml
+singleuser:
+  cmd: jupyterhub-singleuser
+```
+
 (jupyterlab-by-default)=
 
 ## Use JupyterLab by default

jupyterhub/schema.yaml

@@ -1681,7 +1681,18 @@ properties:
               type: string
       cmd:
         type: [array, string, "null"]
-        description: *kubespawner-native-config-description
+        description: |
+          The command and arguments passed to the container.
+          This is the equivalent of the `CMD` Dockerfile instruction.
+          If not set the default from the container image will be used.
+
+          Note that in versions of Z2JH prior to 1.0.0 this was set to
+          `jupyterhub-singleuser` instead of using the image's default.
+
+          See the [KubeSpawner
+          documentation](https://jupyterhub-kubespawner.readthedocs.io/en/latest/spawner.html)
+          for more information.
+
       defaultUrl:
         type: [string, "null"]
         description: *kubespawner-native-config-description