Refs #25850, #27142, #27110 -- Documented migration history consistency checks.

3 files changed, 39 insertions, 5 deletions

diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt
index dde54e936c..1df1f0dcc4 100644
--- a/docs/releases/1.10.txt
+++ b/docs/releases/1.10.txt
@@ -373,9 +373,10 @@ Migrations
 * Added support for :ref:`non-atomic migrations <non-atomic-migrations>` by
   setting the ``atomic`` attribute on a ``Migration``.
 
-* The ``migrate`` and ``makemigrations`` commands now check for a consistent
-  migration history. If they find some unapplied dependencies of an applied
-  migration, ``InconsistentMigrationHistory`` is raised.
+* The ``migrate`` and ``makemigrations`` commands now :ref:`check for a
+  consistent migration history <migration-history-consistency>`. If they find
+  some unapplied dependencies of an applied migration,
+  ``InconsistentMigrationHistory`` is raised.
 
 * The :func:`~django.db.models.signals.pre_migrate` and
   :func:`~django.db.models.signals.post_migrate` signals now dispatch their
diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt
index be976246e6..c16f976911 100644
--- a/docs/topics/db/multi-db.txt
+++ b/docs/topics/db/multi-db.txt
@@ -98,10 +98,22 @@ the database name would raise an error. For the second example::
 Using other management commands
 -------------------------------
 
-The other ``django-admin`` commands that interact with the database operate in
+Most other ``django-admin`` commands that interact with the database operate in
 the same way as :djadmin:`migrate` -- they only ever operate on one database at
 a time, using ``--database`` to control the database used.
 
+An exception to this rule is the :djadmin:`makemigrations` command. It
+validates the migration history in the databases to catch problems with the
+existing migration files (which could be caused by editing them) before
+creating new migrations. By default, it checks only the ``default`` database,
+but it consults the the :meth:`allow_migrate` method of :ref:`routers
+<topics-db-multi-db-routing>` if any are installed.
+
+.. versionchanged:: 1.10
+
+    Migration consistency checks were added. Checks based on database routers
+    were added in 1.10.1.
+
 .. _topics-db-multi-db-routing:
 
 Automatic database routing
@@ -188,7 +200,8 @@ A database Router is a class that provides up to four methods:
     ``model_name`` will be silently skipped when running :djadmin:`migrate` on
     the ``db``. Changing the behavior of ``allow_migrate()`` for models that
     already have migrations may result in broken foreign keys, extra tables,
-    or missing tables.
+    or missing tables. When :djadmin:`makemigrations` verifies the migration
+    history, it skips databases where no app is allowed to migrate.
 
 A router doesn't have to provide *all* these methods -- it may omit one
 or more of them. If one of the methods is omitted, Django will skip
diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
index 9f3635dd4c..0c04fe7295 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -298,6 +298,26 @@ Django checks that all of the respective columns already exist in the database
 and fake-applies the migration if so. Without ``--fake-initial``, initial
 migrations are treated no differently from any other migration.
 
+.. _migration-history-consistency:
+
+History consistency
+-------------------
+
+As previously discussed, you may need to linearize migrations manually when two
+development branches are joined. While editing migration dependencies, you can
+inadvertently create an inconsistent history state where a migration has been
+applied but some of its dependencies haven't. This is a strong indication that
+the dependencies are incorrect, so Django will refuse to run migrations or make
+new migrations until it's fixed. When using multiple databases, you can use the
+:meth:`allow_migrate` method of :ref:`database routers
+<topics-db-multi-db-routing>` to control which databases
+:djadmin:`makemigrations` checks for consistent history.
+
+.. versionchanged:: 1.10
+
+    Migration consistency checks were added. Checks based on database routers
+    were added in 1.10.1.
+
 Adding migrations to apps
 =========================