From 81ebb474aa8f2a1463e6a17b69a216352d95fc53 Mon Sep 17 00:00:00 2001
From: Simon Li <orpheus+devel@gmail.com>
Date: Sat, 28 Sep 2024 19:38:09 +0100
Subject: [PATCH] Add backdated upgrade guide for 2 to 3

---
 docs/source/administrator/upgrading/index.md  |  1 +
 .../administrator/upgrading/upgrade-2-to-3.md | 25 +++++++++++++++++++
 2 files changed, 26 insertions(+)
 create mode 100644 docs/source/administrator/upgrading/upgrade-2-to-3.md

diff --git a/docs/source/administrator/upgrading/index.md b/docs/source/administrator/upgrading/index.md
index f9c6564252..a112e8098e 100644
--- a/docs/source/administrator/upgrading/index.md
+++ b/docs/source/administrator/upgrading/index.md
@@ -22,6 +22,7 @@ or the [Discourse forum](https://discourse.jupyter.org/).
 :maxdepth: 1
 :caption: Major releases guides
 
+upgrade-2-to-3
 upgrade-1-to-2
 ```
 
diff --git a/docs/source/administrator/upgrading/upgrade-2-to-3.md b/docs/source/administrator/upgrading/upgrade-2-to-3.md
new file mode 100644
index 0000000000..addfaa3974
--- /dev/null
+++ b/docs/source/administrator/upgrading/upgrade-2-to-3.md
@@ -0,0 +1,25 @@
+# Major upgrade: 2.\* to 3.\*
+
+Z2JH 3 contains some small breaking changes.
+This guide will help you upgrade from 2.\* to 3.\*.
+
+The minimum supported version of Kubernetes is 1.24.
+
+## JupyterHub 4 and related hub components
+
+Z2JH 3.0.0 upgrades from JupyterHub from 3 to JupyterHub 4.
+There are some minor breaking changes, most notably that XSRF tokens are now used to prevent cross-origin attacks instead of checking the `Referer` header.
+
+The database schema is updated to support new features, but this should not affect existing behaviour.
+Z2JH automatically handles the upgrade if you are using sqlite (`hub.db.type = 'sqlite-pvc'`, the default), but it may not be possible to downgrade to older releases after this.
+If you use an external database you need to configure [`hub.db.upgrade`](schema_hub.db.upgrade) to `true` when upgrading.
+
+KubeSpawner is upgraded from 4 to 6.
+If you set `KubeSpawner.environment` instead of `singleuser.extraEnv` the symbols `{` and `}` are now used for automatic variable expansion. To retain existing behavior, replace `{` and `}` with `{{` and `}}`.
+
+OAuthenticator is upgraded from 15 to 16.
+Previously OAuthenticator would allow any authenticated user by default in most cases.
+This was changed to improve the default security configuration. to retain existing behaviour set `OAuthenticator.allow_all` to `True`.
+
+There are major changes to how the `authenticate()` method is implemented.
+If you are overriding OAuthenticator ensure you [read the changelog for 16](https://github.com/jupyterhub/oauthenticator/blob/16.0.4/docs/source/reference/changelog.md).