Dev docs: Add guidelines on how to use migrations, upgrade and initdb

docs/developers/index.rst

@@ -15,6 +15,7 @@ other way, make sure to read through this part.
    hacking
    customization
    testing
+   initial_data_and_upgrade
    release
    glossary
    styleguide

docs/developers/initial_data_and_upgrade.rst

@@ -0,0 +1,19 @@
+.. _initial-data-and-upgrade:
+
+Initial data and upgrade
+========================
+
+When developing is not uncommon to have to alter the database schema (adding,
+changing or removing fields to models), provide new initial data on fresh
+installations or alter the data on the database when upgrading.
+
+The following guidelines are meant to make clear where to put the code:
+
+- When altering the database schema, add a migration.
+- When adding new initial data, add the code to ``pootle.core.initdb``.
+- When altering the data on the database on upgrading, add the code to
+  ``pootle.apps.pootle_misc.upgrade.pootle``.
+
+  .. note:: If this upgrade code is going to be used for providing initial data
+     as well, then it must be placed instead on ``pootle.core.initdb`` and
+     referenced from ``pootle.apps.pootle_misc.upgrade.pootle``.