diff --git a/docs/changes/2.2.0/822.upgrade.md b/docs/changes/2.2.0/822.upgrade.md
new file mode 100644
index 00000000..8b741660
--- /dev/null
+++ b/docs/changes/2.2.0/822.upgrade.md
@@ -0,0 +1,13 @@
+From the upgrade on, a request that names the role `reader` gets the
+built-in `reader`, which reads every repository, and no longer the role an
+administrator had named `reader`, now `reader-<id>`. Nothing errors:
+`PUT /admin/users/{id}/roles` with `{"role": "reader"}` succeeds and gives
+the account read on every repository, so a script, Terraform module or
+runbook written for 2.1 that assigns that role by name, or looks its id up
+by name in `GET /admin/roles`, widens what its accounts read. Creating a
+role named `reader` (`POST /admin/roles`) answers 409, since the built-in
+role holds the name; a script that takes the 409 for "the role exists"
+goes on with the built-in one. Before upgrading, change such requests to
+pass the role's `role_id`, which the upgrade keeps, or after it to name
+`reader-<id>`. `GET /admin/roles` and **Admin → Roles** list the renamed
+role under its new name.