Document changes regarding migrations

This commit updates the Getting started guide and highlights the upgrade
path for Oscar 0.8.

docs/source/internals/getting_started.rst

@@ -84,7 +84,6 @@ and append Oscar's core apps:
         'django.contrib.staticfiles',
         'django.contrib.flatpages',
         ...
-        'south',
         'compressor',
     ] + get_core_apps()
 
@@ -107,21 +106,16 @@ More info about installing ``flatpages`` is in the `Django docs`_.
 
 Next, add ``oscar.apps.basket.middleware.BasketMiddleware`` and
 ``django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`` to
-your ``MIDDLEWARE_CLASSES`` setting. If you're running on Django 1.5, it is
-also recommended to use ``django.middleware.transaction.TransactionMiddleware``:
+your ``MIDDLEWARE_CLASSES`` setting.
 
 .. code-block:: django
 
     MIDDLEWARE_CLASSES = (
         ...
         'oscar.apps.basket.middleware.BasketMiddleware',
-        'django.middleware.transaction.TransactionMiddleware',  # Django 1.5 only
         'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware',
     )
 
-If you're running Django 1.6 or above, you should enable ``ATOMIC_REQUESTS``
-instead (see database settings above).
-
 Set your auth backends to:
 
 .. code-block:: django
@@ -237,7 +231,7 @@ Check your database settings. A quick way to get started is to use SQLite:
             'PASSWORD': '',
             'HOST': '',
             'PORT': '',
-            'ATOMIC_REQUESTS': True,  # Django 1.6+
+            'ATOMIC_REQUESTS': True,
         }
     }
 
@@ -255,8 +249,32 @@ Then create the database and the shop should be browsable:
 You should now have an empty, but running Oscar install that you can browse at
 http://localhost:8000.
 
-Fixtures
-========
+Migrations
+----------
+
+Oscar ships with two sets of migrations. If you're running Django 1.7, you
+don't need to do anything; Django's migration framework will detect them
+automatically and will do the right thing.
+If you're running Django 1.6, you need to install `South`_::
+
+.. code-block:: bash
+
+    $ pip install South
+
+And you need to add it to your installed apps:
+
+.. code-block:: django
+
+    INSTALLED_APPS = [
+        ...
+        'south',
+    ] + get_core_apps()
+
+.. _South: http://south.readthedocs.org/en/latest/
+
+
+Initial data
+============
 
 The default checkout process requires a shipping address with a country.  Oscar
 uses a model for countries with flags that indicate which are valid shipping

docs/source/releases/v0.8.rst

@@ -81,6 +81,17 @@ has been altered to be:
 Some properties and method names have also been updated to the new naming. The
 old ones will throw a deprecation warning.
 
+Django 1.7 support
+------------------
+
+Oscar 0.8 comes with support for Django 1.7 out of the box. The app refactor
+and the new migration framework are both great improvements to Django. Oscar
+now ships with sets of migrations both for South and the new native
+migrations framework.
+Unfortunately, the changes in Django required a few breaking changes when
+upgrading Oscar both for users staying on Django 1.6 and for users upgrading to
+Django 1.7 at the same time.
+
 Reworked shipping app
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -205,12 +216,44 @@ Minor changes
   populate the country databases. It replaces the ``countries.json`` fixture.
   The command relies on the ``pycountry`` library being installed.
 
+* It is now possible to use product attributes to add a relation to arbitrary
+  model instances. There was some (presumably broken) support for it before,
+  but you should now be able to use product attributes of type ``entity`` as
+  expected. There's currently no frontend or dashboard support for it, as there
+  is no good default behaviour.
+
 .. _incompatible_changes_in_0.8:
 
 Backwards incompatible changes in 0.8
 -------------------------------------
 
-.. _incompatible_shipping_changes_in_0.8:
+Migrations
+~~~~~~~~~~
+
+* South is not a dependency of Oscar anymore: This means it won't get installed
+  automatically when you install Oscar. If you are on Django 1.6 and want to
+  use South, you will need to explicitly install it and add it to your
+  requirements.
+* Only South >= 1.0 is supported: South 1.0 is a backwards compatible release
+  explicitly released to help with the upgrade path to Django 1.7. Please make
+  sure you update accordingly if you intend to keep using South. Older versions
+  of South will look in the wrong directories and will break with this Oscar
+  release.
+* Rename your South ``migrations`` directories: To avoid
+  clashes between Django's migrations and South's migrations, you should rename
+  all your South migrations directories (including those of forked Oscar apps)
+  to ``south_migrations``. South 1.0 will check those first before falling back
+  to ``migrations``.
+* Upgrading to new-style migrations: If you're upgrading to Django 1.7, you
+  will need to follow the `instructions to upgrade from South`_ for your own
+  apps. For any forked Oscar apps, you will need to copy Oscar's initial
+  migrations into your emptied ``migrations`` directory first, because Oscar's
+  set of migrations depend on each other. You can then create migrations for
+  your changes by calling ``./manage.py makemigrations``. Django should
+  detect that the database layout already matches the state of migrations; so
+  a call to ``migrate`` should fake the migrations.
+
+.. _instructions to upgrade from South: https://docs.djangoproject.com/en/1.7/topics/migrations/#upgrading-from-south
 
 Product structure
 ~~~~~~~~~~~~~~~~~
@@ -237,6 +280,8 @@ The following methods and properties have been deprecated:
 * ``Strategy.select_variant_stockrecords`` - Use
   ``select_children_stockrecords`` instead.
 
+.. _incompatible_shipping_changes_in_0.8:
+
 Shipping
 ~~~~~~~~
 
@@ -378,11 +423,11 @@ Misc
   trivial ``ProductAttribute.get_validator`` and the unused
   ``ProductAttribute.is_value_valid`` methods have been removed.
 
-* It is now possible to use product attributes to add a relation to arbitrary
-  model instances. There was some (presumably broken) support for it before,
-  but you should now be able to use product attributes of type ``entity`` as
-  expected. There's currently no frontend or dashboard support for it, as there
-  is no good default behaviour.
+* The ``RangeProductFileUpload`` model has been moved from the ranges
+  dashboard app to the offers app. The migrations that have been naively
+  drop and re-create the model; any data is lost! This is probably not an
+  issue, as the model is only used while an range upload is in progress. If
+  you need to keep the data, ensure you migrate it across.
 
 .. _rewritten: https://github.com/tangentlabs/django-oscar/commit/d8b4dbfed17be90846ea4bc47b5f7b39ad944c24
 
@@ -451,13 +496,11 @@ Migrations
     Please double-check it's outcome and make sure to do something similar
     if you have forked the catalogue app.
 
-.. warning::
+.. note::
 
-    The ``RangeProductFileUpload`` model has been moved from the ranges
-    dashboard app to the offers app. The migrations that have been naively
-    drop and re-create the model; any data is lost! This is probably not an
-    issue, as the model is only used while an range upload is in progress. If
-    you need to keep the data, ensure you migrate it across.
+    The migration numbers below refer to the numbers of the South migrations.
+    Oscar 0.8 ships with a set of new initial migrations for Django's new
+    native migrations framework. They include all the changes detailed below.
 
 .. note::