[6.0.x] Fixed #36844 -- Clarified need for reusable apps to set default_auto_field in packaging tutorial and AppConfig docs.

Backport of 091ffc4e5eb35776864b853973097588a36f169e from main.

2 files changed, 16 insertions, 5 deletions

diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt
index 627cf3292e..bb33dc0197 100644
--- a/docs/intro/reusable-apps.txt
+++ b/docs/intro/reusable-apps.txt
@@ -143,8 +143,10 @@ this. For a small app like polls, this process isn't too difficult.
    to ``django_polls``.
 
 #. Edit ``django_polls/apps.py`` so that :attr:`~.AppConfig.name` refers to the
-   new module name and add :attr:`~.AppConfig.label` to give a short name for
-   the app:
+   new module name, add :attr:`~.AppConfig.label` to give a short name for
+   the app, and set :attr:`~.AppConfig.default_auto_field` to ensure your
+   migrations are not affected by changes to :setting:`DEFAULT_AUTO_FIELD`
+   made by users of your reusable app:
 
    .. code-block:: python
        :caption: ``django-polls/django_polls/apps.py``
@@ -153,6 +155,7 @@ this. For a small app like polls, this process isn't too difficult.
 
 
        class PollsConfig(AppConfig):
+           default_auto_field = "django.db.models.BigAutoField"
            name = "django_polls"
            label = "polls"
 
diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt
index 7801e8f438..ce6d559488 100644
--- a/docs/ref/applications.txt
+++ b/docs/ref/applications.txt
@@ -227,9 +227,17 @@ Configurable attributes
 
 .. attribute:: AppConfig.default_auto_field
 
-    The implicit primary key type to add to models within this app. You can
-    use this to keep :class:`~django.db.models.AutoField` as the primary key
-    type for third party applications.
+    The implicit primary key type to add to models within this app.
+
+    Reusable applications that define models **must** set this attribute to
+    ensure migrations included in the application match the models. Otherwise,
+    migrations will be generated for the application when a user runs
+    :djadmin:`makemigrations` with a different :setting:`DEFAULT_AUTO_FIELD`,
+    which may conflict with future migrations shipped by the application.
+
+    For example, to keep using :class:`~django.db.models.AutoField`::
+
+        default_auto_field = "django.db.models.AutoField"
 
     By default, this is the value of :setting:`DEFAULT_AUTO_FIELD`.