launchpad-reviewers team mailing list archive

[Raphaël Badin <raphael.badin@xxxxxxxxxxxxx>]

Raphaël Badin has proposed merging lp:~rvb/maas/maas-south-tutorial into lp:maas.

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~rvb/maas/maas-south-tutorial/+merge/99486

Add a quick South tutorial.
-- 
https://code.launchpad.net/~rvb/maas/maas-south-tutorial/+merge/99486
Your team Launchpad code reviewers is requested to review the proposed merge of lp:~rvb/maas/maas-south-tutorial into lp:maas.

=== modified file 'HACKING.txt'
--- HACKING.txt	2012-03-23 18:12:27 +0000
+++ HACKING.txt	2012-03-27 10:12:26 +0000
@@ -208,6 +208,59 @@
 directory.
 
 
+Database schema changes
+=======================
+
+MAAS uses South_ to manage changes to the database schema.
+
+.. _South: http://south.aeracode.org
+
+Be sure to have a look at `South's documentation`_ before you make any change.
+
+.. _South's documentation: http://south.aeracode.org/docs/
+
+Changing the schema
+^^^^^^^^^^^^^^^^^^^
+
+Once you've made a change to ``src/<application>/models.py`` you have to run  
+South's `schemamigration`_ command to create a migration file that will be
+stored in ``src/<application>/migrations/``.
+
+.. _schemamigration: http://south.aeracode.org/docs/commands.html#schemamigration
+
+For instance if you're making changes to ``src/maasserver/models.py``, you
+will need to run::
+
+    $ ./bin/maas schemamigration maasserver --auto description_of_the_change
+
+This will generate a migration module named
+``src/maasserver/migrations/<auto_number>_description_of_the_change.py``.
+
+To apply that migration, run::
+
+    $ make syncdb
+
+Performing data migration
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you need to perform data migration, very much in the same way, you will need
+to run South's `datamigration`_ command.  For instance, if you want to perform
+changes to the ``maasserver`` application, run::
+
+    $ ./bin/maas datamigration maasserver --auto description_of_the_change
+
+.. _datamigration: http://south.aeracode.org/docs/commands.html#datamigration
+
+This will generate a migration module named
+``src/maasserver/migrations/<auto_number>_description_of_the_change.py``.
+You will need to edit that file and fill the ``forwards`` and ``backwards``
+methods were data should be actually migrated.
+
+Once the methods have been written, apply that migration with::
+
+    $ make syncdb
+
+
 Documentation
 =============
 
@@ -233,7 +286,7 @@
 To run them::
 
     $ checkbox-gtk --config='checkbox/plugins/jobs_info/directories=\
-    /path/to/local/checkbox/jobs/dir' --whitelist-file=
+        /path/to/local/checkbox/jobs/dir' --whitelist-file=
 
 or run from the root of the MAAS tree::