[Django] #36844: Update packaging tutorial and AppConfig docs to mandate setting default_auto_field for reusable apps

[Django]

#36844: Update packaging tutorial and AppConfig docs to mandate setting
default_auto_field for reusable apps
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: dev | Severity: Normal
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
A reusable (third-party) app that:
- has models
- but does ''not'' set `AppConfig.default_auto_field`

is in a
[https://github.com/django/django/pull/20319#discussion_r2631747194
"completely broken" situation], given that any user attempting to use
`DEFAULT_AUTO_FIELD` in their own settings will generate migrations for
the reusable app, which can conflict with later migrations shipped by that
app, or possibly get stored in the app's installation location:

> Third-party apps should set default_auto_field so that the migrations
the app includes match the models.

This discussion took place in a
[https://github.com/django/django/pull/20319 PR that was not accepted]
proposing to advise on user workarounds. Instead, I think we should advise
app authors to do the right thing.

That would include:
- strengthening the wording in `AppConfig.default_auto_field` docs,
replacing "You can use this... for third party applications" to something
like "Third-party applications *must* set this ..."
- Fixing the tutorial to show this step under
[https://docs.djangoproject.com/en/dev/intro/reusable-apps/#packaging-
your-app "Packaging your app"]. To my knowledge (I'm hoping someone will
confirm), when you follow the tutorial and arrive at this step modeling
how to make your app reusable, there is no `default_auto_field` attribute
on the `AppConfig` in apps.py.

This would be an approachable issue for a new contributor, as it involves
following the tutorial to verify completeness and accuracy.
--
Ticket URL: <https://code.djangoproject.com/ticket/36844>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36844: Update packaging tutorial and AppConfig docs to mandate setting
default_auto_field for reusable apps

--------------------------------------+------------------------------------
Reporter: Jacob Walls | Owner: (none)

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Tim Graham):

* stage: Unreviewed => Accepted

--
Ticket URL: <https://code.djangoproject.com/ticket/36844#comment:1>

[Django]

#36844: Update packaging tutorial and AppConfig docs to mandate setting
default_auto_field for reusable apps
--------------------------------------+------------------------------------

Reporter: Jacob Walls | Owner: Amar
Type: Cleanup/optimization | Status: assigned

Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Amar):

* owner: (none) => Amar
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/36844#comment:2>

[Django]

#36844: Update packaging tutorial and AppConfig docs to mandate setting
default_auto_field for reusable apps
--------------------------------------+------------------------------------
Reporter: Jacob Walls | Owner: Amar
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Changes (by Amar):

* has_patch: 0 => 1

Comment:

PR submitted: https://github.com/django/django/pull/20503
This patch:
- Updates the `AppConfig.default_auto_field` documentation to clarify
that reusable applications **must** set this attribute
- Adds `default_auto_field` to the `PollsConfig` example in the
packaging tutorial

This follows the guidance from the discussion in PR #20319.
--
Ticket URL: <https://code.djangoproject.com/ticket/36844#comment:3>

[Django]

#36844: Update packaging tutorial and AppConfig docs to mandate setting
default_auto_field for reusable apps

-------------------------------------+-------------------------------------

Reporter: Jacob Walls | Owner: Amar

Type: | Status: assigned
Cleanup/optimization |

Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Jacob Walls):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/36844#comment:4>

[Django]

#36844: Update packaging tutorial and AppConfig docs to mandate setting
default_auto_field for reusable apps
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Amar

Type: | Status: closed

Cleanup/optimization |
Component: Documentation | Version: dev

Severity: Normal | Resolution: fixed

Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Jacob Walls <jacobtylerwalls@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"091ffc4e5eb35776864b853973097588a36f169e" 091ffc4e]:
{{{#!CommitTicketReference repository=""
revision="091ffc4e5eb35776864b853973097588a36f169e"
Fixed #36844 -- Clarified need for reusable apps to set default_auto_field
in packaging tutorial and AppConfig docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36844#comment:5>

[Django]

#36844: Update packaging tutorial and AppConfig docs to mandate setting
default_auto_field for reusable apps
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Amar
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Jacob Walls <jacobtylerwalls@…>):

In [changeset:"8230e9b7fad10d4a13a9d6c1001782f799f567c6" 8230e9b]:
{{{#!CommitTicketReference repository=""
revision="8230e9b7fad10d4a13a9d6c1001782f799f567c6"
[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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36844#comment:6>