more links, references in upgrade docs

- add explicit discussion of static subPath
- remove redundant version update references
- remove OAuthenticator change references

docs/source/administrator/upgrading/upgrade-3-to-4.md

@@ -6,13 +6,19 @@ zero-to-jupyterhub 4.0 is a major upgrade that may require some changes to your
 depending on what features you may use.
 This mostly comes in the form of some upgraded packages, described below.
 
-See the [changelog](changelog) for details of upgraded packages.
+:::{seealso}
+
+- the [general upgrade documentation](upgrading-major-upgrades) for upgrade steps to take every time you do a major chart update
+- the [changelog](changelog-4.0) for details of upgraded packages
+
+:::
 
 ## JupyterHub 5
 
 zero-to-jupyterhub 4.0 upgrades the JupyterHub version from 4.1.6 to 5.2.1.
 
 :::{seealso}
+
 For more detailed changes in JupyterHub, see JupyterHub's own documentation on upgrading to version 5:
 
 Especially if you use features like per-user subdomains or custom page templates.
@@ -49,10 +55,12 @@ especially those that have the `{username}` or `{servername}` fields,
 those values are likely to change under the new scheme for some usernames.
 In particular, there are new fields that should make things easier:
 
-- `{user_server}` combines the username and server name, and is equivalent to `{username}{servername}` in the old escape scheme
-- `{pod_name}`, `{pvc_name}`
+- `{user_server}` combines the username and server name, and is equivalent to `{username}{servername}` in the old escape scheme.
+  It is the recommended value when a string should be unique per named server, as opposed to per user.
+- `{pod_name}`, `{pvc_name}` are now available to reference the fully resolved names of these objects
+  and can be used to avoid duplicating templates.
 
-You can opt in to the kubespawner 6 behavior with:
+You can opt in globally to keep the kubespawner 6 behavior with:
 
 ```yaml
 hub:
@@ -63,23 +71,32 @@ hub:
 
 which _should_ result in no changes for you from previous behavior.
 
-:::{seealso}
+One user-facing place where a default template may require administrator action is if you are using:
 
-- [KubeSpawner changelog](https://jupyterhub-kubespawner.readthedocs.io/en/latest/changelog.html)
-- [KubeSpawner docs on templated fields](https://jupyterhub-kubespawner.readthedocs.io/en/latest/templates.html#fields)
+```yaml
+singleuser:
+  storage:
+    type: static
+```
 
-:::
+The default value for `subPath` is `{username}` which may resolve to a different value for some usernames, which could appear like a 'lost' home directory because the mount path changes.
+The data is not lost, but the mount location has changed.
+To ensure this value doesn't change, you can use:
 
-## OAuthenticator 17
+```yaml
+singleuser:
+  storage:
+    type: static
+    static:
+      subPath: "{escaped_username}"
+```
 
-OAuthenticator is upgraded from 16.3.1 to 17.1.
-The main changes are related to using group information from OAuth providers.
-If you used or would like to use groups for authentication,
-check out the [OAuthenticator changelog](https://oauthenticator.readthedocs.io/en/stable/reference/changelog.html)
+which applies the previous 'escape' scheme to the subPath.
+Alternatively, you can keep the new scheme, and perform a one-time migration to move files for the affected usernames.
 
-## Other package upgrades
+:::{seealso}
 
-- Python is upgraded from 3.11 to 3.12 in the Hub image
-- LDAPAuthenticator is upgraded from 1 to 2 ([changelog](https://github.com/jupyterhub/ldapauthenticator/blob/2.0.0/CHANGELOG.md#200---2024-10-18))
-- FirstUseAuthenticator is upgraded from 1.0 to 1.1 ([changelog](https://github.com/jupyterhub/firstuseauthenticator/blob/1.1.0/CHANGELOG.md))
-- idle culler is upgraded from 1.3.1 to 1.4.0 ([changelog](https://github.com/jupyterhub/jupyterhub-idle-culler/blob/1.4.0/CHANGELOG.md))
+- [KubeSpawner changelog](https://jupyterhub-kubespawner.readthedocs.io/en/latest/changelog.html)
+- [KubeSpawner docs on templated fields](https://jupyterhub-kubespawner.readthedocs.io/en/latest/templates.html#fields)
+
+:::

docs/source/changelog.md

@@ -10,19 +10,27 @@ This Helm chart provides [development releases], and as we merge [breaking
 changes in pull requests], this list should be updated.
 
 [development releases]: https://hub.jupyter.org/helm-chart/#development-releases-jupyterhub
+
 [breaking changes in pull requests]: https://github.com/jupyterhub/zero-to-jupyterhub-k8s/pulls?q=is%3Apr+is%3Aclosed+label%3Abreaking
 
+(changelog-4.0)=
+
 ## 4.0
 
-### 4.0.0 - 2024-10
+### 4.0.0 - 2024-11
 
 This release updates JupyterHub itself from version 4 to 5, and the dependencies
 `jupyterhub-kubespawner`, `oauthenticator`, and `ldapauthenticator` to a new
 major version.
 
-See the [upgrade guide](upgrade-3-to-4) for specific instructions for upgrading chart version from 3 to 4,
-and check the summary of breaking changes and the linked changelogs below
-if you use any of the upgraded packages.
+:::{seealso}
+
+- the [general upgrade documentation](upgrading-major-upgrades) for upgrade steps to take every time you do a major chart update
+- the [upgrade guide](upgrade-3-to-4) for specific instructions for upgrading chart version from 3 to 4
+- check the summary of breaking changes and the linked changelogs below
+  if you use any of the upgraded packages.
+
+:::
 
 #### Breaking changes
 

docs/source/conf.py

@@ -38,6 +38,7 @@
 # ref: https://myst-parser.readthedocs.io/en/latest/configuration.html
 #
 myst_enable_extensions = [
+    "colon_fence",
     "substitution",
 ]