Update the upgrade notes (#6050)

 * 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.

2 files changed, 54 insertions, 27 deletions

diff --git a/UPGRADE.rst b/UPGRADE.rst
index 53f3af4ed1..4ede973a08 100644
--- a/UPGRADE.rst
+++ b/UPGRADE.rst
@@ -2,52 +2,78 @@ 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
+     # replace `1.3.0` accordingly:
+     pip install matrix-synapse==1.3.0
+
+* 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 0000000000..3d19c69bc4
--- /dev/null
+++ b/changelog.d/6050.doc
@@ -0,0 +1 @@
+Update the upgrade notes.