diff --git a/changelog.d/16951.doc b/changelog.d/16951.doc new file mode 100644 index 0000000000000000000000000000000000000000..a7fb33979d5ae9b3c74f0953d0e091d3b48a0f0d --- /dev/null +++ b/changelog.d/16951.doc @@ -0,0 +1 @@ +Add docs on upgrading from a very old version. \ No newline at end of file diff --git a/docs/upgrade.md b/docs/upgrade.md index 7f67ef88067cb10f0158724f1ffc108c421efa28..640fed3ae386a0afce83be1ab10cfdbca03bb9eb 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -97,6 +97,26 @@ v1.61.0. <!-- REPLACE_WITH_SCHEMA_VERSIONS --> +## Upgrading from a very old version + +You need to read all of the upgrade notes for each version between your current +version and the latest so that you can update your dependencies, environment, +config files, etc. if necessary. But you do not need to perform an +upgrade to each individual version that was missed. + +We do not have a list of which versions must be installed. Instead, we recommend +that you upgrade through each incompatible database schema version, which would +give you the ability to roll back the maximum number of versions should anything +go wrong. See [Rolling back to older versions](#rolling-back-to-older-versions) +above. + +Additionally, new versions of Synapse will occasionally run database migrations +and background updates to update the database. Synapse will not start until +database migrations are complete. You should wait until background updates from +each upgrade are complete before moving on to the next upgrade, to avoid +stacking them up. You can monitor the currently running background updates with +[the Admin API](usage/administration/admin_api/background_updates.html#status). + # Upgrading to v1.100.0 ## Minimum supported Rust version diff --git a/docs/usage/administration/admin_faq.md b/docs/usage/administration/admin_faq.md index 5c9ee7d0aa6f380d4541c7e33bdf74ce155fee97..092dcc1c846cb1f0228b2b670565dc77c982292b 100644 --- a/docs/usage/administration/admin_faq.md +++ b/docs/usage/administration/admin_faq.md @@ -120,6 +120,11 @@ for file in $source_directory/*; do done ``` +How do I upgrade from a very old version of Synapse to the latest? +--- +See [this](../../upgrade.html#upgrading-from-a-very-old-version) section in the +upgrade docs. + Manually resetting passwords --- Users can reset their password through their client. Alternatively, a server admin