Finished first version of south migration mini-HowTo.

README.develop

@@ -192,7 +192,8 @@ South Database Migration
 First, remember to add the south app to settings.py (it is already included in the
 settings.py.dist).
 
-In addition, do not use the syncdb management command. Only the first time
+In addition, do not use the syncdb management command. Only the first time and if you
+drop the database and must create it from the start.
 
 The first time (is not required, since when you read this documentation the migration
 is already active) the migration of the schema will initialised with the following
@@ -227,6 +228,49 @@ in a model, we should declare its default value. If not, south management will p
 
 If we need to do data migration as well, for example rename a field, we use tha 'datamigration' management command.
 
+In contrast with schemamigration, to perform complex data migration, we must write the script manually. The process is
+the following:
+
+    1. Introduce the changes in the code and fixtures (initial data).
+    2. Execute:
+
+    $ ./bin/python manage.py datamigration <migration_name_here>
+
+    For example:
+
+    $ ./bin/python manage.py datamigration db rename_credit_wallet
+    Created 0003_rename_credit_wallet.py.
+
+    3. We edit the generated script. It contains two methods: forwards and backwards.
+
+    For database operations (column additions, alter tables etc) we use the South database API
+    (http://south.aeracode.org/docs/databaseapi.html).
+
+    To access the data, we use the database reference (orm) provided as parameter in the forwards, backwards declarations.
+    For example:
+
+    class Migration(DataMigration):
+
+    def forwards(self, orm):
+        orm.SynnefoUser.objects.all()
+
+    4. To migrate the database to the latest version, we execute:
+
+    ./manage.py migrate db
+
+To see which migrations are applied:
+
+    $ ./bin/python manage.py migrate db --list
+
+      db
+        (*) 0001_initial
+        (*) 0002_auto__add_field_synnefouser_new_south_test_field
+        (*) 0003_rename_credit_wallet
+
+More information and more thorough examples can be found in the South web site.
+
+http://south.aeracode.org/
+
 UI Testing
 ----------
 The functional ui tests require the Selenium server and the synnefo app to