diff --git a/docs/changes/2.2.0/788.upgrade.md b/docs/changes/2.2.0/788.upgrade.md
new file mode 100644
index 00000000..d4be3aaa
--- /dev/null
+++ b/docs/changes/2.2.0/788.upgrade.md
@@ -0,0 +1,19 @@
+**Stop every 2.1 instance before the first 2.2.0 instance starts**, rather
+than rolling the upgrade. The first 2.2.0 instance migrates the database,
+and 2.1 instances that still serve then go wrong in three ways. They sign
+no one in through a credential-forwarding realm: 2.2.0 writes the new
+`accept_client_passwords` setting into the realm of `[auth.upstream_basic]`
+when it first starts (and into any such realm it saves), 2.1 cannot read
+the realm then and skips it ("credential-forwarding realm skipped"), and
+its users get 401 from those instances. An image retention policy saved on
+2.2.0 with a glob in `protected_tags` deletes, when a 2.1 instance runs it,
+the old tags the glob protects, since 2.1 reads `release-*` as a tag's
+name; 2.1 also ignores the package delay's per-package overrides. And an
+account a 2.1 instance creates (an OIDC or trusted-header first sign-in) or
+sets to Reader gets no built-in `reader` role, which the upgrade gives only
+to the accounts that exist when it runs: on 2.2.0 it is Roles only and
+reads nothing. With the Helm chart, upgrade with
+`--set strategy.type=Recreate` or scale the deployment to zero first; with
+the Kubernetes manifests, scale the `forge` deployment to zero before
+applying 2.2.0. After an upgrade that rolled, look in **Admin → Users** for
+accounts created meanwhile whose access level is Roles only.