Add documentation on manually upgrading a StoryBoard instance

Sometimes it is necessary to upgrade the database of a manually
deployed StoryBoard instance, for example when updating a test
server being used for development.

This commit adds some documentation on how the `storyboard-db-manage`
command-line tool can be used to upgrade and downgrade the
database.

Change-Id: I0ac21ddc3bacac7105efda7258e7ae52818f8f69

doc/source/index.rst

@@ -38,8 +38,15 @@ Installation guides
 
    install/development
 
-Migration guides
+Maintenance guides
-----------------
+------------------
+.. toctree::
+   :maxdepth: 1
+
+   maintenance/upgrading
+
+Launchpad Migration guides
+--------------------------
 .. toctree::
    :maxdepth 1
 

doc/source/maintenance/upgrading.rst

@@ -0,0 +1,82 @@
+====================================================
+Manually Upgrading/Downgrading a StoryBoard Instance
+====================================================
+
+If you have a manually deployed StoryBoard instance, for example a local
+server for development, you may sometimes need to upgrade the database as
+new changes are merged upstream.
+
+Similarly, you may wish to rollback a change to for testing purposes. This
+guide will explain how you can use the ``storyboard-db-manage`` tool to
+upgrade and downgrade your database schema.
+
+If using ``tox``, all commands in this guide should be run as ::
+
+    $ tox -e venv -- $command
+
+You may find you need to prepend ``sudo`` to this command.
+
+
+Checking the current version
+============================
+
+If you don't know what version your database is currently, you can check it
+with::
+
+    $ storyboard-db-manage --config-file /path/to/storyboard.conf current
+
+
+Upgrading the database
+======================
+
+If your existing database version is currently < 049, you are advised to
+run the upgrade command using commit ``acce431b30a32497064ad6d1ab3872358e1e60dc``
+of the storyboard repository, since after that the migrations were consolidated
+and will no longer work with existing databases older than version 049.
+
+You can upgrade to the latest database version in-place with the following
+command::
+
+    $ storyboard-db-manage --config-file /path/to/storyboard.conf upgrade head
+
+Replacing ``head`` in this command allows you to specify a target version. For
+example, this command will upgrade to version 055::
+
+    $ storyboard-db-manage --config-file /path/to/storyboard.conf upgrade 055
+
+It is also possible to create an sql script to upgrade the database offline::
+
+    $ storyboard-db-manage --config-file /path/to/storyboard.conf upgrade head --sql
+
+Additionally, you can generate a script to upgrade between two versions with::
+
+    $ storyboard-db-manage --config-file /path/to/storyboard.conf \
+        upgrade <start version>:<end version> --sql
+
+You can also upgrade the database incrementally, by specifying the number of
+revisions to apply::
+
+    $ storyboard-db-manage --config-file /path/to/storyboard.conf \
+        upgrade --delta <# of revs>
+
+
+Downgrading the database
+========================
+
+If you need to downgrade to a version > 001 and < 049, you will need to first
+downgrade to version 049, then use commit ``acce431b30a32497064ad6d1ab3872358e1e60dc``
+to downgrade further to the version you require. After this commit, the
+migrations lower than 049 were consolidated and can no longer be used
+individually.
+
+Downgrade the database by a certain number of revisions::
+
+    $ storyboard-db-manage --config-file /path/to/storyboard.conf \
+        downgrade --delta <# of revs>
+
+You can also downgrade to a specific version::
+
+    $ storyboard-db-manage --config-file /path/to/storyboard.conf downgrade 055
+
+Similar to upgrading, you can use the ``--sql`` flag to generate an sql script
+to be applied later.

storyboard/db/migration/README

@@ -20,32 +20,6 @@ can run sequentially to update the database. The scripts are executed by
 storyboard's migration wrapper which uses the Alembic library to manage the
 migration.
 
-If your existing database version is currently < 049, you are advised to
-run the upgrade command using commit `acce431b30a32497064ad6d1ab3872358e1e60dc`
-of this repository, since after that the migrations were consolidated and
-will no longer work with existing databases older than version 049.
-
-You can upgrade to the latest database version via:
-$ storyboard-db-manage --config-file /path/to/storyboard.conf upgrade head
-
-To check the current database version:
-$ storyboard-db-manage --config-file /path/to/storyboard.conf current
-
-To create a script to run the migration offline:
-$ storyboard-db-manage --config-file /path/to/storyboard.conf upgrade head --sql
-
-To run the offline migration between specific migration versions:
-$ storyboard-db-manage --config-file /path/to/storyboard.conf \
-    upgrade <start version>:<end version> --sql
-
-Upgrade the database incrementally:
-$ storyboard-db-manage --config-file /path/to/storyboard.conf \
-    upgrade --delta <# of revs>
-
-Downgrade the database by a certain number of revisions:
-$ storyboard-db-manage --config-file /path/to/storyboard.conf \
-    downgrade --delta <# of revs>
-
 This utility should be also used to load Project Groups and Projects form a .yaml
 file description. The description sample is provided in etc/projects.yaml.
 $ storyboard-db-manage --config-file /path/to/storyboard.conf \