Document South->built-in migrations transition

[Karen Tracey]

Neither the 1.7 release notes nor ​https://docs.djangoproject.com/en/dev/topics/migrations/ says anything about how someone who has a project currently using south for schema migrations would transition to using the built-in Migrations of 1.7.

I assumed you could upgrade to 1.7 yet continue with existing south until you were ready to make the switch, at which point you'd essentially drop all the history you have with south and switch over to the new way going forward. Is that the plan?

However existing south doesn't work with current master, due to:

(django17-test) kmtracey@caktus006 16:42:54: ~/projects/playground
--> ./manage.py migrate --list
Traceback (most recent call last):
  File "./manage.py", line 10, in <module>
    execute_from_command_line(sys.argv)
  File "/home/kmtracey/django/git-django/django/core/management/__init__.py", line 426, in execute_from_command_line
    utility.execute()
  File "/home/kmtracey/django/git-django/django/core/management/__init__.py", line 418, in execute
    self.fetch_command(subcommand).run_from_argv(self.argv)
  File "/home/kmtracey/django/git-django/django/core/management/__init__.py", line 290, in fetch_command
    klass = load_command_class(app_name, subcommand)
  File "/home/kmtracey/django/git-django/django/core/management/__init__.py", line 81, in load_command_class
    module = import_module('%s.management.commands.%s' % (app_name, name))
  File "/usr/lib/python2.7/importlib/__init__.py", line 37, in import_module
    __import__(name)
  File "/home/kmtracey/.virtualenvs/django17-test/local/lib/python2.7/site-packages/south/management/commands/__init__.py", line 12, in <module>
    from south.hacks import hacks
  File "/home/kmtracey/.virtualenvs/django17-test/local/lib/python2.7/site-packages/south/hacks/__init__.py", line 8, in <module>
    from south.hacks.django_1_0 import Hacks
  File "/home/kmtracey/.virtualenvs/django17-test/local/lib/python2.7/site-packages/south/hacks/django_1_0.py", line 8, in <module>
    from django.db.models.loading import cache
ImportError: cannot import name cache

That strikes me as a problem introduced by the app-loading refactor...but due to lack of doc on how people who use south are supposed to move up to 1.7 I don't know if that's a problem that should be fixed in a release of south before 1.7 goes out or not. The first thing that's needed is some doc on how people are supposed to make this transition.

[Andrew Godwin]

I'll write this soon. The issue that South doesn't work with 1.7 is going to persist - there's no point fixing it so it does (as 1.7 already has migrations) and even if I wanted to, it would be a massive change (as the AppCache removal means I'd need to rewrite large portions of South)

[Andrew Godwin]

This is now documented: ​https://docs.djangoproject.com/en/dev/topics/migrations/#upgrading-from-south

[Luke Plant]

These instructions work OK for projects, but for resuable apps it is harder. Most re-usable apps will need to support several Django versions, and 1.7 adoption is going to be severely hindered if it isn't possible for an app to support both 1.7 and earlier versions.

It seems that it should be possible to support this by use of MIGRATION_MODULES. e.g. you can put MIGRATION_MODULES = {'foo': 'foo.migrations_17'} (or django_migrations or something) if you are running foo on Django 1.7 (because the old South migrations will be in foo.migrations, and they will need to stay there AFAICS).

It would really help with the upgrade to 1.7 if this was documented, and all apps adopted the same conventions and strategy.

Actually, I was hoping for much better support for this use case. What will happen if someone upgrades to Django 1.7 and runs ./manage.py migrate with South installed and various South migrations still in place (from their main project and all the 3rd party stuff)? This is going to be so common that I think that graceful detection of this situation should be a release blocker.

[Andrew Godwin]

This is meant to be the purpose of South 2 - it will support the same migration format as 1.7, but run on versions 1.4 - 1.6, so you can follow the same process for reusable apps as long as you tell your users to also use South 2 (which cannot be used alongside South 1, but that's a separate issue unfortunately).

./manage.py migrate already detects and ignores directories full of South migrations, we could make it list the ones it ignores on the list it outputs, however. If South is installed it'll immediately crash as it doesn't work with 1.7; I'll release a final 0.x update that has a few other bugfixes and a nice error message saying "this won't work with 1.7" before I release 2.0.