Fixed #24375 -- Added Migration.initial attribute

The new attribute is checked when the `migrate --fake-initial` option
is used. initial will be set to True for all initial migrations (this
is particularly useful when initial migrations are split) as well as
for squashed migrations.

2 files changed, 37 insertions, 6 deletions

diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 4e8fad3bf8..d87e0a6618 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -368,6 +368,14 @@ Management Commands
   to the database using the password from your settings file (instead of
   requiring it to be manually entered).
 
+Migrations
+^^^^^^^^^^
+
+* Initial migrations are now marked with an :attr:`initial = True
+  <django.db.migrations.Migration.initial>` class attribute which allows
+  :djadminopt:`migrate --fake-initial <--fake-initial>` to more easily detect
+  initial migrations.
+
 Models
 ^^^^^^
 
diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
index 75373537c4..82354f96a8 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -276,6 +276,33 @@ class to make it importable::
 Please refer to the notes about :ref:`historical-models` in migrations to see
 the implications that come along.
 
+Initial migrations
+~~~~~~~~~~~~~~~~~~
+
+.. attribute:: Migration.initial
+
+.. versionadded:: 1.9
+
+The "initial migrations" for an app are the migrations that create the first
+version of that app's tables. Usually an app will have just one initial
+migration, but in some cases of complex model interdependencies it may have two
+or more.
+
+Initial migrations are marked with an ``initial = True`` class attribute on the
+migration class. If an ``initial`` class attribute isn't found, a migration
+will be considered "initial" if it is the first migration in the app (i.e. if
+it has no dependencies on any other migration in the same app).
+
+When :djadmin:`migrate` is run with the :djadminopt:`--fake-initial` option,
+these initial migrations are treated specially. For an initial migration that
+creates one or more tables (``CreateModel`` operation), Django checks that all
+of those tables already exist in the database and fake-applies the migration
+if so. Similarly, for an initial migration that adds one or more fields
+(``AddField`` operation), Django checks that all of the respective columns
+already exist in the database and fake-applies the migration if so. Without
+:djadminopt:`--fake-initial`, initial migrations are treated no differently
+from any other migration.
+
 Adding migrations to apps
 -------------------------
 
@@ -425,6 +452,7 @@ Then, open up the file; it should look something like this::
     from django.db import models, migrations
 
     class Migration(migrations.Migration):
+        initial = True
 
         dependencies = [
             ('yourappname', '0001_initial'),
@@ -460,6 +488,7 @@ need to do is use the historical model and iterate over the rows::
             person.save()
 
     class Migration(migrations.Migration):
+        initial = True
 
         dependencies = [
             ('yourappname', '0001_initial'),
@@ -761,12 +790,6 @@ If you already have pre-existing migrations created with
   without running them. (Django won't check that the table schema match your
   models, just that the right table names exist).
 
-That's it! The only complication is if you have a circular dependency loop
-of foreign keys; in this case, ``makemigrations`` might make more than one
-initial migration, and you'll need to mark them all as applied using::
-
-    python manage.py migrate --fake yourappnamehere
-
 .. versionchanged:: 1.8
 
     The :djadminopt:`--fake-initial` flag was added to :djadmin:`migrate`;