From 35ce3bda7aaa6281f02123225ca63d913fa12df1 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Thu, 19 Sep 2019 15:06:48 +0100
Subject: [PATCH] Add some notes on rolling back to v1.3.1. (#6049)

---
 UPGRADE.rst          | 25 +++++++++++++++++++++++++
 changelog.d/6049.doc |  1 +
 2 files changed, 26 insertions(+)
 create mode 100644 changelog.d/6049.doc

diff --git a/UPGRADE.rst b/UPGRADE.rst
index 5aaf80490..53f3af4ed 100644
--- a/UPGRADE.rst
+++ b/UPGRADE.rst
@@ -99,6 +99,31 @@ Synapse will expect these files to exist inside the configured template director
 default templates, see `synapse/res/templates
 <https://github.com/matrix-org/synapse/tree/master/synapse/res/templates>`_.
 
+Rolling back to v1.3.1
+----------------------
+
+If you encounter problems with v1.4.0, it should be possible to roll back to
+v1.3.1, subject to the following:
+
+* The 'room statistics' engine was heavily reworked in this release (see
+  `#5971 <https://github.com/matrix-org/synapse/pull/5971>`_), including
+  significant changes to the database schema, which are not easily
+  reverted. This will cause the room statistics engine to stop updating when
+  you downgrade.
+
+  The room statistics are essentially unused in v1.3.1 (in future versions of
+  Synapse, they will be used to populate the room directory), so there should
+  be no loss of functionality. However, the statistics engine will write errors
+  to the logs, which can be avoided by setting the following in `homeserver.yaml`:
+
+  .. code:: yaml
+
+    stats:
+      enabled: false
+
+  Don't forget to re-enable it when you upgrade again, in preparation for its
+  use in the room directory!
+
 Upgrading to v1.2.0
 ===================
 
diff --git a/changelog.d/6049.doc b/changelog.d/6049.doc
new file mode 100644
index 000000000..e0307bf5c
--- /dev/null
+++ b/changelog.d/6049.doc
@@ -0,0 +1 @@
+Add some notes on rolling back to v1.3.1.