Add generic update instructions to UPGRADE.rst and add link to them from the README.rst

README.rst

@@ -362,14 +362,11 @@ This should end with a 'PASSED' result::
 Upgrading an existing Synapse
 =============================
 
-IMPORTANT: Before upgrading an existing synapse to a new version, please
-refer to UPGRADE.rst for any additional instructions.
-
-Otherwise, simply re-install the new codebase over the current one - e.g.
-by ``pip install --process-dependency-links
-https://github.com/matrix-org/synapse/tarball/master``
-if using pip, or by ``git pull`` if running off a git working copy.
+The instructions for upgrading synapse are in `UPGRADE.rst`_.
+Please check these instructions as upgrading may require extra steps for some
+versions of synapse.
 
+.. _UPGRADE.rst: UPGRADE.rst
 
 Setting up Federation
 =====================

UPGRADE.rst

@@ -1,3 +1,36 @@
+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
+instructions that may be required are listed later in this document.
+
+If you installed synapse in a virtualenv then active that virtualenv before
+upgrading. If synapse is installed in a virtualenv in ``~/.synapse/`` then run:
+
+.. code:: bash
+
+    source ~/.synapse/bin/activate
+
+If you installed synapse using pip then upgrade to the latest version by
+running:
+
+.. code:: bash
+
+    pip install --upgrade --process-dependency-links https://github.com/matrix-org/synapse/tarball/master
+
+If you installed synapse using git then upgrade to the latest version by
+running:
+
+.. code:: bash
+
+    # Pull the latest version of the master branch.
+    git pull
+    # Update the versions of synapses python dependencies.
+    python synapse/python_dependencies.py | xargs -n1 pip install
+
+
+
 Upgrading to v0.9.0
 ===================