From 679193744d89756721ec16369647ae05cb4cbd31 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Wed, 18 Sep 2019 12:06:00 +0100
Subject: [PATCH] Update the upgrade notes

 * make it clear that if you installed from a package manager, you should use
   that to upgrade

 * Document the new way of getting the server version (cf #4878)

 * Write some words about downgrading.
---
 UPGRADE.rst          | 78 +++++++++++++++++++++++++++++---------------
 changelog.d/6050.doc |  1 +
 2 files changed, 52 insertions(+), 27 deletions(-)
 create mode 100644 changelog.d/6050.doc

diff --git a/UPGRADE.rst b/UPGRADE.rst
index 5aaf804902ed..480ee3e69c6c 100644
--- a/UPGRADE.rst
+++ b/UPGRADE.rst
@@ -2,52 +2,76 @@ Upgrading Synapse
 =================
 
 Before upgrading check if any special steps are required to upgrade from the
-what you currently have installed to current version of synapse. The extra
+what you currently have installed to current version of Synapse. The extra
 instructions that may be required are listed later in this document.
 
-1. If synapse was installed in a virtualenv then activate that virtualenv before
-   upgrading. If synapse is installed in a virtualenv in ``~/synapse/env`` then
-   run:
+* If Synapse was installed using `prebuilt packages
+  <INSTALL.md#prebuilt-packages>`_, you will need to follow the normal process
+  for upgrading those packages.
 
-   .. code:: bash
+* If synapse was installed from source, then:
 
-       source ~/synapse/env/bin/activate
-
-2. If synapse was installed using pip then upgrade to the latest version by
-   running:
+  1. Activate the virtualenv before upgrading. For example, if synapse is
+     installed in a virtualenv in ``~/synapse/env`` then run:
 
-   .. code:: bash
+     .. code:: bash
 
-       pip install --upgrade matrix-synapse[all]
+       source ~/synapse/env/bin/activate
 
-       # restart synapse
-       synctl restart
+  2. If synapse was installed using pip then upgrade to the latest version by
+     running:
 
+     .. code:: bash
 
-   If synapse was installed using git then upgrade to the latest version by
-   running:
+       pip install --upgrade matrix-synapse
 
-   .. code:: bash
+     If synapse was installed using git then upgrade to the latest version by
+     running:
 
-       # Pull the latest version of the master branch.
+     .. code:: bash
        git pull
+       pip install --upgrade .
 
-       # Update synapse and its python dependencies.
-       pip install --upgrade .[all]
+   3. Restart synapse:
 
-       # restart synapse
-       ./synctl restart
+      .. code:: bash
 
+         ./synctl restart
 
-To check whether your update was successful, you can check the Server header
-returned by the Client-Server API:
+To check whether your update was successful, you can check the running server
+version with:
 
 .. code:: bash
 
-    # replace <host.name> with the hostname of your synapse homeserver.
-    # You may need to specify a port (eg, :8448) if your server is not
-    # configured on port 443.
-    curl -kv https://<host.name>/_matrix/client/versions 2>&1 | grep "Server:"
+    # you may need to replace 'localhost:8008' if synapse is not configured
+    # to listen on port 8008.
+
+    curl http://localhost:8008/_synapse/admin/v1/server_version
+
+Rolling back to older versions
+------------------------------
+
+Rolling back to previous releases can be difficult, due to database schema
+changes between releases. Where we have been able to test the rollback process,
+this will be noted below.
+
+In general, you will need to undo any changes made during the upgrade process,
+for example:
+
+* pip:
+
+  .. code:: bash
+
+     source env/bin/activate
+     pip install matrix-synapse==<version>
+
+* Debian:
+
+  .. code:: bash
+
+     # replace `1.3.0` and `stretch` accordingly:
+     wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb
+     dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
 
 Upgrading to v1.4.0
 ===================
diff --git a/changelog.d/6050.doc b/changelog.d/6050.doc
new file mode 100644
index 000000000000..3d19c69bc468
--- /dev/null
+++ b/changelog.d/6050.doc
@@ -0,0 +1 @@
+Update the upgrade notes.