add migration doc for 5.0

docs/source/howto/upgrading-v5.md

@@ -0,0 +1,144 @@
+(upgrading-v5)=
+
+# Upgrading to JupyterHub 5
+
+This document describes the specific considerations.
+For general upgrading tips, see the [docs on upgrading jupyterhub](upgrading).
+
+You can see the [changelog](changelog) for more detailed information.
+
+## Python version
+
+JupyterHub 5 requires Python 3.8.
+Make sure you have at least Python 3.8 in your user and hub environments before upgrading.
+
+## Database upgrades
+
+JupyterHub 5 does have a database schema upgrade,
+so you should backup your database and run `jupyterhub upgrade-db` after upgrading and before starting JupyterHub.
+The updated schema only adds some columns, so is one that should be not too disruptive to roll back if you need to.
+
+## User subdomains
+
+All JupyterHub deployments which care about protecting users from each other are encouraged to enable per-user domains, if possible,
+as this provides the best isolation between user servers.
+
+To enable subdomains, set:
+
+```python
+c.JupyterHub.subdomain_host = "https://myjupyterhub.example.org"
+```
+
+If you were using subdomains before
+
+JupyterHub 5 allows complete customization of the subdomain scheme and changes the default subdomain scheme.
+via the new {attr}`.JupyterHub.subdomain_hook`.
+
+You can provide a completely custom subdomain scheme, or select one of two default implementations by name: `idna` or `legacy`. `idna` is the default.
+
+The new default behavior can be selected explicitly via:
+
+```python
+c.JupyterHub.subdomain_hook = "idna"
+```
+
+Or to delay any changes to URLs for your users, you can opt-in to the pre-5.0 behavior with:
+
+```python
+c.JupyterHub.subdomain_hook = "legacy"
+```
+
+The key differences of the new `idna` scheme:
+
+- It should always produce valid domains, regardless of username (not true for the legacy scheme when using characters that might need escaping or usernames that are long)
+- each Service gets its own subdomain on `service--` rather than sharing `services.`
+
+A table of example of user and services, and their domains with the old and new scheme.
+
+In the examples below, we'll assume the configuration enabling subdomains:
+
+```python
+c.JupyterHub.subdomain_host = "https://jupyter.example.org"
+```
+
+| kind    | name               | legacy                                                     | idna                                                                                                  |
+| ------- | ------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| user    | laudna             | `laudna.jupyter.example.org`                               | `laudna.jupyter.example.org`                                                                          |
+| service | bells              | `services.jupyter.example.org`                             | `bells--service.jupyter.example.org`                                                                  |
+| user    | jester@mighty.nein | `jester_40mighty.nein.jupyter.example.org` (may not work!) | `u-jestermi--8037680.jupyter.example.org` (not as pretty, but guaranteed to be valid and not collide) |
+
+## Tokens in URLs
+
+JupyterHub 5 does not accept `?token=...` URLs by default in single-user servers.
+These URLs allow one user to force another to login as them,
+which can be the start of an inter-user attack.
+
+There is a valid use case for producing links which allow starting a fully authenticated session,
+so you may still opt in to this behavior by setting:
+
+```python
+c.Spawner.environment.update({"JUPYTERHUB_ALLOW_TOKEN_IN_URL": "1"})
+```
+
+if you are not concerned about protecting your users from each other.
+If you have subdomains enabled, the threat is substantially reduced.
+
+## Sharing
+
+The big new feature in JupyterHub 5.0 is sharing.
+Check it out in [the sharing docs](sharing-tutorial).
+
+## Authenticator.allow_all and allow_existing_users
+
+Prior to JupyterHub 5, JupyterHub Authenticators had the _implicit_ default behavior to allow any user who successfully authenticates to login **if no users are explicitly allowed** (i.e. `allowed_users` is empty on the base class).
+This behavior was considered a too-permissive default in Authenticators that source large user pools like OAuthenticator, which would accept e.g. all users with a Google account by default.
+As a result, OAuthenticator 16 introduced two configuration options:
+
+1. `Authenticator.allow_all` (default: False)
+2. `Authenticator.allow_existing_users` (default: True if allowed_users is non-empty, False otherwise)
+
+JupyterHub 5 adopts these options for all Authenticators,
+essentially having the effect that _some_ allow configuration is required for anyone to be able to login.
+If you want to preserve the pre-5.0 behavior with no `allow` configuration, set:
+
+```python
+c.Authenticator.allow_all = True
+```
+
+`allow_existing_users` defaults are meant to be backward-compatible, but you can now _explicitly_ allow or disallow based on presence in the database by setting `Authenticator.allow_existing_users`.
+
+:::{seealso}
+
+[Authenticator config docs](authenticators) for details on these and other Authenticator options.
+:::
+
+## Bootstrap 5
+
+JupyterHub uses the CSS framework [bootstrap](https://getbootstrap.com), which is upgraded from 3.4 to 5.3.
+If you don't have any custom HTML templates, you are likely to only see relatively minor aesthetic changes.
+If you have custom HTML templates or spawner options forms, they may need some updating to look right.
+
+See the bootstrap documentation. Since we upgraded two major versions, you might need to look at both v4 and v5 documentation for what has changed since 3.x:
+
+- [migrating to v4](https://getbootstrap.com/docs/4.6/migration/)
+- [migrating to v5](https://getbootstrap.com/docs/5.3/migration/)
+
+If you customized the JupyterHub CSS by recompiling from LESS files, bootstrap migrated to SCSS.
+You can start by autoconverting your LESS to SCSS (it's not that different) with [less2sass](https://github.com/ekryski/less2sass):
+
+```bash
+npm install --global less2scss
+# converts less/foo.less to scss/foo.scss
+less2scss --src ./less --dst ./scss
+```
+
+Bootstrap also allows configuring things with [CSS variables](https://getbootstrap.com/docs/5.3/customize/css-variables/), so depending on what you have customized, you may be able to get away with just adding a CSS file defining variables without rebuilding the whole SCSS.
+
+## groups required with Authenticator.manage_groups
+
+Setting `Authenticator.manage_groups = True` allows the Authenticator to manage group membership by returning `groups` from the authentication model.
+However, this option is available even on Authenticators that do not support it, which led to confusion.
+Starting with JupyterHub 5, if `manage_groups` is True `authenticate` _must_ return a groups field, otherwise an error is raised.
+This prevents confusion when users enable managed groups that is not implemented.
+
+If an Authenticator _does_ support managing groups but was not providing a `groups` field in order to leave membership unmodified, it must specify `"groups": None` to make this explicit instead of implicit (this is backward-compatible).

docs/source/howto/upgrading.md

@@ -14,6 +14,14 @@ JupyterHub is painless, quick and with minimal user interruption.
 
 The steps are discussed in detail, so if you get stuck at any step you can always refer to this guide.
 
+For specific version migrations:
+
+```{toctree}
+:maxdepth: 1
+
+./upgrading-v5
+```
+
 ## Read the Changelog
 
 The [changelog](changelog) contains information on what has