summary refs log tree commit diff
diff options
context:
space:
mode:
authorTwilight Sparkle <19155609+Twi1ightSparkle@users.noreply.github.com>2024-02-22 17:36:41 +0000
committerGitHub <noreply@github.com>2024-02-22 17:36:41 +0000
commit8de3283ebe520e945ccfb66242f4795ecdd0d1f4 (patch)
treed74c4bef95f32770905d58f6be9af6b65cadf758
parentBump anyhow from 1.0.79 to 1.0.80 (#16935) (diff)
downloadsynapse-8de3283ebe520e945ccfb66242f4795ecdd0d1f4.tar.xz
Add docs on upgrading from a very old version (#16951)
Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
-rw-r--r--changelog.d/16951.doc1
-rw-r--r--docs/upgrade.md20
-rw-r--r--docs/usage/administration/admin_faq.md5
3 files changed, 26 insertions, 0 deletions
diff --git a/changelog.d/16951.doc b/changelog.d/16951.doc
new file mode 100644
index 0000000000..a7fb33979d
--- /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 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
diff --git a/docs/usage/administration/admin_faq.md b/docs/usage/administration/admin_faq.md
index 5c9ee7d0aa..092dcc1c84 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