[1.7.x] Fixed #23090: Document and enforce not double-squashing migrations

2 files changed, 19 insertions, 0 deletions

diff --git a/django/core/management/commands/squashmigrations.py b/django/core/management/commands/squashmigrations.py
index c4f9326c5d..8795947296 100644
--- a/django/core/management/commands/squashmigrations.py
+++ b/django/core/management/commands/squashmigrations.py
@@ -70,6 +70,8 @@ class Command(BaseCommand):
         # Load the operations from all those migrations and concat together
         operations = []
         for smigration in migrations_to_squash:
+            if smigration.replaces:
+                raise CommandError("You cannot squash squashed migrations! Please transition it to a normal migration first: https://docs.djangoproject.com/en/1.7/topics/migrations/#squashing-migrations")
             operations.extend(smigration.operations)
 
         if self.verbosity > 0:
diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
index 80a86dee20..c9d6ee0e5d 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -487,6 +487,23 @@ please `file a bug report <https://code.djangoproject.com/newticket>`_ either
 way detailing the models and their relationships so we can improve the
 optimizer to handle your case.
 
+Once you've squashed your migration, you should then commit it alongside the
+migrations it replaces and distribute this change to all running instances
+of your application, making sure that they run ``migrate`` to store the change
+in their database.
+
+After this has been done, you must then transition the squashed migration to
+a normal initial migration, by:
+
+- Deleting all the migration files it replaces
+- Removing the ``replaces`` argument in the ``Migration`` class of the
+  squashed migration (this is how Django tells that it is a squashed migration)
+
+.. note::
+    Once you've squashed a migration, you should not then re-squash that squashed
+    migration until you have fully transitioned it to a normal migration.
+
+
 .. _migration-serializing:
 
 Serializing values