Improve docs on how to handle migrations when upgrading

As it came up on the mailing list again, I've clarified a few more
scenarios of what needs to be done with migrations when upgrading.

docs/source/releases/v0.7.rst

@@ -318,6 +318,11 @@ Migrations
     affected ``None``'s to ``''`` yourself; see the data migrations for our
     approach.
 
+.. note::
+
+    Be sure to read the detailed instructions for
+    :doc:`handling migrations </topics/upgrading>`.
+
 * Address:
 
     - ``0008`` - Forgotten migration for ``UserAddress.phone_number``

docs/source/releases/v0.8.rst

@@ -161,10 +161,12 @@ Cleanup around shipping methods
 
 * ``WeightBand.upper_limit`` is now a ``DecimalField``, just like the other
   weight-related fields.
+
     - Stand-alone product: Products that "stand by themselves", neither have
       parent nor children.
     - Parent product: An overarching product, previously known as group product.
     - Child products: Products related to a common parent product
+
 .. _minor_changes_in_0.8:
 
 Minor changes
@@ -220,6 +222,7 @@ unavoidable:
   to ``children``.
 
 The following methods and properties have been deprecated:
+
 * ``Product.is_parent`` - Use ``is_group`` instead.
 * ``Product.is_variant`` - Use ``is_child`` instead.
 * ``Product.is_top_level`` - Test for ``is_standalone`` and/or ``is_parent`` instead.
@@ -443,6 +446,11 @@ Migrations
     Please double-check it's outcome and make sure to do something similar
     if you have forked the catalogue app.
 
+.. note::
+
+    Be sure to read the detailed instructions for
+    :doc:`handling migrations </topics/upgrading>`.
+
 * Address:
 
     - ``0011`` - ``AbstractAddress.search_text`` turned into a ``TextField``.

docs/source/topics/upgrading.rst

@@ -5,13 +5,6 @@ Upgrading
 This document explains some of the issues that can be encountered whilst
 upgrading Oscar.
 
-.. note::
-
-    Detailed upgrade instructions for specific releases can be found on the `Github
-    wiki`_.
-
-.. _`Github wiki`: https://github.com/tangentlabs/django-oscar/wiki/Upgrading
-
 Migrations
 ----------
 
@@ -37,14 +30,44 @@ For instance,  if you have ``oscar.apps.core.shipping`` in your
 
 to migrate your shipping app.
 
-Migrating customised apps
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Migrating customised apps (models unchanged)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have customised an app, but have not touched the models nor migrations,
+you're best off copying the migrations from Oscar.  This approach has the
+advantage of pulling in any data migrations.
+Find the updated(!) Oscar in your virtualenv or clone the Oscar repo at the
+correct version tag. Then find the migrations, copy them across, and migrate as
+usual.  You will have to adapt paths, but something akin to this will work::
 
-For apps that you are customising, you need to create a new migration that picks
-up the changes in the core Oscar models.
-For instance,  if you have an app ``myproject.shipping`` that replaces
-``oscar.apps.shipping`` in your ``INSTALLED_APPS`` then you can simply run::
+    $ cdsitepackages oscar/apps/shipping/migrations
+    $ copy *.py <your_project>/myshop/shipping/migrations/
+
+Migrating customised apps (models changed)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At this point, you have essentially forked away from Oscar's migrations. Read
+the release notes carefully and see if it includes data migrations. If not,
+it's as easy as::
 
     ./manage.py schemamigration shipping --auto
 
 to create the appropriate migration.
+
+But if there is data migrations, you will need to look into what they do, and
+likely will have to imitate what they're doing. You can't just copy across the
+entire data migration (because the South's fake ORM snapshot will be wrong),
+but you can usually create a data migration like this::
+
+    ./manage.py datamigration shipping descriptive_name
+
+and then copy the code portion from Oscar's migration into your newly
+created migration.
+
+If there's also schema migrations, then you need to also create a schema
+migration::
+
+    ./manage.py schemamigration shipping --auto
+
+The fun part is figuring out if you have to create the schema migration before
+or after the data migration.