[1.8.x] Fixed #24882 -- Documented Migration.run_before

Backport of dee1bcd08a013ba5ffd8d1ec9b6628702f755066 from master

1 files changed, 41 insertions, 0 deletions

diff --git a/docs/howto/writing-migrations.txt b/docs/howto/writing-migrations.txt
index 2daf6ade7a..1e77434b95 100644
--- a/docs/howto/writing-migrations.txt
+++ b/docs/howto/writing-migrations.txt
@@ -183,3 +183,44 @@ the respective field according to your needs.
   Note there is a race condition if you allow objects to be created while this
   migration is running. Objects created after the ``AddField`` and before
   ``RunPython`` will have their original ``uuid``’s overwritten.
+
+Controlling the order of migrations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django determines the order in which migrations should be applied not by the
+filename of each migration, but by building a graph using two properties on the
+``Migration`` class: ``dependencies`` and ``run_before``.
+
+If you've used the :djadmin:`makemigrations` command you've probably
+already seen ``dependencies`` in action because auto-created
+migrations have this defined as part of their creation process.
+
+The ``dependecies`` property is declared like this::
+
+    from django.db import migrations
+
+    class Migration(migrations.Migration):
+
+        dependencies = [
+            ('myapp', '0123_the_previous_migration'),
+        ]
+
+Usually this will be enough, but from time to time you may need to
+ensure that your migration runs *before* other migrations. This is
+useful, for example, to make third-party apps' migrations run *after*
+your :setting:`AUTH_USER_MODEL` replacement.
+
+To achieve this, place all migrations that should depend on yours in
+the ``run_before`` attribute on your ``Migration`` class::
+
+    class Migration(migrations.Migration):
+        ...
+
+        run_before = [
+            ('third_party_app', '0001_do_awesome'),
+        ]
+
+Prefer using ``dependencies`` over ``run_before`` when possible. You should
+only use ``run_before`` if it is undesirable or impractical to specify
+``dependencies`` in the migration which you want to run after the one you are
+writing.