Add db migration doc

Change-Id: Ie47ebbcdedc34af4ab510cbecdb9faa79d02810f

doc/source/contributor/make-changes-to-database.rst

@@ -0,0 +1,45 @@
+==============================
+Making changes to the database
+==============================
+
+In order to make a change to the mogan database you must update the database
+models and then create a migration to reflect that change.
+
+There are two ways to create a migration which are described below, both of
+these generate a new migration file. In this file there is only one function:
+
+* ``upgrade`` - The function to run when
+    ``mogan-dbsync upgrade`` is run, and should be populated with
+    code to bring the database up to its new state from the state it was in
+    after the last migration.
+
+For further information on creating a migration, refer to
+`Create a Migration Script`_ from the alembic documentation.
+
+Autogenerate
+------------
+
+This is the simplest way to create a migration. Alembic will compare the models
+to an up to date database, and then attempt to write a migration based on the
+differences. This should generate correct migrations in most cases however
+there are some cases when it can not detect some changes and may require
+manual modification, see `What does Autogenerate Detect (and what does it not
+detect?)`_ from the alembic documentation.
+
+::
+
+    mogan-dbsync upgrade
+    mogan-dbsync revision -m "A short description" --autogenerate
+
+Manual
+------
+
+This will generate an empty migration file, with the correct revision
+information already included. However the upgrade function is left empty
+and must be manually populated in order to perform the correct actions on
+the database::
+
+    mogan-dbsync revision -m "A short description"
+
+.. _Create a Migration Script: http://alembic.zzzcomputing.com/en/latest/tutorial.html#create-a-migration-script
+.. _What does Autogenerate Detect (and what does it not detect?): http://alembic.zzzcomputing.com/en/latest/autogenerate.html#what-does-autogenerate-detect-and-what-does-it-not-detect

doc/source/index.rst

@@ -26,6 +26,21 @@ Mogan is an OpenStack project which offers bare metals as first class
 resources to users, supporting variety of bare metal provisioning drivers
 including Ironic.
 
+Contributor Guide
+=================
+
+If you are new to mogan, this section contains information that should help
+you get started as a developer working on the project or contributing to the
+project.
+
+.. toctree::
+  :maxdepth: 1
+
+  contributor/code-contribution-guide
+  contributor/dev-quickstart
+  contributor/make-changes-to-database
+  contributor/testing
+
 Installation Guide
 ==================
 
@@ -65,21 +80,6 @@ Configuration Guide
   configuration/sample_policy
 
 
-Contributor Guide
-=================
-
-If you are new to mogan, this section contains information that should help
-you get started as a developer working on the project or contributing to the
-project.
-
-.. toctree::
-  :maxdepth: 1
-
-  contributor/code-contribution-guide
-  contributor/dev-quickstart
-  contributor/testing
-
-
 Command References
 ==================