add some upgrade instructions

README.md

@@ -244,6 +244,49 @@ cluster if you add or remove one backend, moving databases and blogs
 around.
 
 
+Upgrades
+--------
+
+The upgrade procedure involves upgrading the source repository on all
+your servers, and running database upgrades for each blog. In order to
+upgrade your installation, you will need the `noblogs` tool from the
+`noblogs-cli` repository.
+
+### Upgrading the source code
+
+We rebase our patch set on top of the Wordpress upstream on every
+release, creating a new versioned branch of our repository. So the
+first step is to figure out the most recent version is (our versioning
+does not necessarily follow the Wordpress versioning scheme): you can
+check the available branches in the git web interface for this
+repository. At the time of this writing, the current version is
+`noblogs-2.1.10`, which we will use in the example below.
+
+The following commands should upgrade your installation in place:
+
+    $ git remote update
+    $ git fetch noblogs-2.1.10
+
+### Running database upgrades
+
+The Network Upgrade option from the Wordpress admin panel does not
+really work reliably, especially on large installations (due to request
+timeouts and memory issues), so it is advised to use the `noblogs`
+command-line tool to perform post-upgrade maintenance tasks.
+
+Assuming you have installed `noblogs-cli` in `/opt/noblogs`, the
+following commands will upgrade the database schema for all blogs:
+
+    $ /opt/noblogs/bin/on-all-blogs upgrade
+
+Note that this requires passwordless SSH access to the backend
+servers. Otherwise you can always run
+
+    $ /opt/noblogs/bin/on-local-blogs upgrade
+
+manually on each backend.
+
+
 Contributing to the project
 ---------------------------