From a714262827d8fbe40b34675dac15ff4456f1d4d4 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Mon, 27 Nov 2023 14:43:12 -0500
Subject: [PATCH] Clarifications & updates.

---
 docs/upgrade.md                | 10 ++++++----
 scripts-dev/schema_versions.py | 34 ++++++++++++++++++++++------------
 2 files changed, 28 insertions(+), 16 deletions(-)

diff --git a/docs/upgrade.md b/docs/upgrade.md
index bcccfae7bb7a..329c9c778713 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -88,10 +88,12 @@ process, for example:
     dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
     ```
 
-Generally Synapse database schemas are compatible across the following versions.
-The left column is the latest Synapse version which can be rolled back to the right
-column. E.g. Synapse versions v1.13.0 through v1.44.0 can be rolled back safely to
-v1.13.0.
+Generally Synapse database schemas are compatible across multiple versions, once
+a version of Synapse is deployed you may not be able to rollback automatically.
+The following table gives the version ranges and the earliest version they can
+be rolled back to. E.g. Synapse versions v1.58.0 through v1.61.1 can be rolled
+back safely to v1.57.0, but starting with v1.62.0 it is only safe to rollback to
+v1.61.0.
 
 <!-- REPLACE_WITH_SCHEMA_VERSIONS -->
 
diff --git a/scripts-dev/schema_versions.py b/scripts-dev/schema_versions.py
index 08c15c6b62c6..e699af2f38e8 100755
--- a/scripts-dev/schema_versions.py
+++ b/scripts-dev/schema_versions.py
@@ -117,30 +117,40 @@ def calculate_version_chart() -> str:
     schema_version = None
     schema_compat_version = None
 
-    # Map of schema version -> Synapse versions at that schema.
+    # Map of schema version -> Synapse versions which are at that schema version.
     schema_versions = defaultdict(list)
+    # Map of schema version -> Synapse versions which are compatible with that
+    # schema version.
+    schema_compat_versions = defaultdict(list)
 
     # Find ranges of versions which are compatible with a schema version.
     #
     # There are two modes of operation:
     #
-    # 1. If schema_compat_version is None, then Synapse can only move to a new
-    #    version with schema_version >= its current version.
-    # 2. If schema_compat_version is *not* None, then Synapse can move to a new
-    #    version with schema version >= schema_compat_version.
+    # 1. Pre-schema_compat_version (i.e. schema_compat_version of None), then
+    #    Synapse is compatible up/downgrading to a version with
+    #    schema_version >= its current version.
+    #
+    # 2. Post-schema_compat_version (i.e. schema_compat_version is *not* None),
+    #    then Synapse is compatible up/downgrading to a version with
+    #    schema version >= schema_compat_version.
+    #
+    #    This is more generous and avoids versions that cannot be rolled back.
     #
     # See https://github.com/matrix-org/synapse/pull/9933 which was included in v1.37.0.
     for tag in get_tags(repo):
         schema_version, schema_compat_version = get_schema_versions(tag)
 
         # If a schema compat version is given, prefer that over the schema version.
-        schema_versions[schema_compat_version or schema_version].append(tag.name)
-
-    # Generate a table of which maps a version to the version it can be rolled back to.
-    result = "| Synapse version | Backwards compatible version |\n"
-    result += "|-----------------|------------------------------|\n"
-    for synapse_versions in schema_versions.values():
-        result += f"| {synapse_versions[-1]: ^15} | {synapse_versions[0]: ^28} |\n"
+        schema_versions[schema_version].append(tag.name)
+        schema_compat_versions[schema_compat_version or schema_version].append(tag.name)
+
+    # Generate a table which maps the latest Synapse version compatible with each
+    # schema version.
+    result = "| Compatible versions | Earliest version |\n"
+    result += "|{'-' * (19 + 2)}|{'-' * (18 + 2)|\n"
+    for schema_version, synapse_versions in schema_compat_versions.items():
+        result += f"| {synapse_versions[0] + ' - ' + synapse_versions[-1]: ^19} | {schema_versions[schema_version][0]: ^18} |\n"
 
     return result