[1.7.x] Fixed #22660: Doc'd you can't have unmigrated apps depend on migrated

3 files changed, 31 insertions, 0 deletions

diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index b7acc6247a..52f02e1b29 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -1063,6 +1063,12 @@ avoid the overhead of an index if you are creating a foreign key for
 consistency rather than joins, or if you will be creating an alternative index
 like a partial or multiple column index.
 
+.. warning::
+
+    It is not recommended to have a ``ForeignKey`` from an app without migrations
+    to an app with migrations. See the :ref:`dependencies documentation
+    <unmigrated-dependencies>` for more details.
+
 Database Representation
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1266,6 +1272,12 @@ which the model is related, which works exactly the same as it does for
 Related objects can be added, removed, or created with the field's
 :class:`~django.db.models.fields.related.RelatedManager`.
 
+.. warning::
+
+    It is not recommended to have a ``ManyToManyField`` from an app without migrations
+    to an app with migrations. See the :ref:`dependencies documentation
+    <unmigrated-dependencies>` for more details.
+
 Database Representation
 ~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index 9a02fc0428..3ab136d24b 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -68,6 +68,10 @@ but a few of the key features are:
   inside ``TransactionTestCase`` :ref:`unless specifically requested
   <test-case-serialized-rollback>`.
 
+* It is not advised to have apps without migrations depend on (have a
+  :ref:`ForeignKey <ref-foreignkey>` or :ref:`ManyToManyField <ref-manytomany>` to) apps with migrations. Read the
+  :ref:`dependencies documentation <unmigrated-dependencies>` for more.
+
 .. _app-loading-refactor-17-release-note:
 
 App-loading refactor
diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
index 40ce520a03..a4fc5c9e52 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -201,6 +201,21 @@ restrict to a single app. Restricting to a single app (either in
 a guarantee; any other apps that need to be used to get dependencies correct
 will be.
 
+.. _unmigrated-dependencies:
+
+Be aware, however, that unmigrated apps cannot depend on migrated apps, by the
+very nature of not having migrations. This means that it is not generally
+possible to have an unmigrated app have a ForeignKey or ManyToManyField to
+a migrated app; some cases may work, but it will eventually fail.
+
+This is particularly apparent if you use swappable models (e.g.
+``AUTH_USER_MODEL``), as every app that uses swappable models will need
+to have migrations if you're unlucky. As time goes on, more and more
+third-party apps will get migrations, but in the meantime you can either
+give them migrations yourself (using :setting:`MIGRATION_MODULES` to
+store those modules outside of the app's own module if you wish), or
+keep the app with your user model unmigrated.
+
 .. _migration-files:
 
 Migration files