Add docs on upgrading from a very old version (#16951)
Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
1 files changed, 20 insertions, 0 deletions
diff --git a/docs/upgrade.md b/docs/upgrade.md
index 7f67ef8806..640fed3ae3 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
|
