[Django] #36665: Rewrite reference to model manager usage to avoid saying "tricky"

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Type:
| Cleanup/optimization
Status: new | Component: Database
| layer (models, ORM)
Version: dev | Severity: Normal
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
In the
[https://docs.djangoproject.com/en/5.2/topics/db/optimization/#:~:text=tricky%20so%20don%E2%80%99t%20make%20assumptions.
database optimization doc], there is this advice:

> Understand select_related() and prefetch_related() thoroughly, and use
them:

> - in managers and default managers where appropriate. Be aware when your
manager is and is not used; sometimes this is tricky so don’t make
assumptions.

Saying something is "tricky" and immediately moving on leaves the
impression of information hiding. Let's at least link to something that
explains what to watch out for or debug. In other words, we need to answer
the question, "wait, when ''wouldn't'' my model manager be used"?

(The location of this text is moving in #28586.)
--
Ticket URL: <https://code.djangoproject.com/ticket/36665>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------

Reporter: Jacob Walls | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:

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

Changes (by Jacob Walls):

* component: Database layer (models, ORM) => Documentation

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

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: (none)
Type: | Status: new
Cleanup/optimization |

Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

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

Changes (by Natalia Bidart):

* component: Documentation => Database layer (models, ORM)
* stage: Unreviewed => Accepted

Comment:

Thank you Jacob, I agre that this change will make these docs more
approachable and less scary. I think the original Component set to ORM is
correct, since we tend to use "Documentation" for tickets around the
process of building/handling docs, not the doc content itself.
--
Ticket URL: <https://code.djangoproject.com/ticket/36665#comment:2>

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Jacob Walls):

Super, thanks for confirming.

> we tend to use "Documentation" for tickets around the process of
building/handling docs, not the doc content itself.

You bring up a long-time point of confusion for me. Elsewhere like the
[https://code.djangoproject.com/wiki/Reports Trac reports], it's implied
that the documentation component includes doc content, e.g. "Documentation
patches that need review" or "Documentation tickets that need patches". I
wouldn't expect those to only link to sphinx/infra related tickets.
--
Ticket URL: <https://code.djangoproject.com/ticket/36665#comment:3>

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------

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

Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Segni Mekonnen):

* has_patch: 0 => 1
* owner: (none) => Segni Mekonnen
* status: new => assigned

Comment:

Working on this ticket. Will submit PR shortly.

This ticket asks to replace vague "tricky" language with specific examples
of when managers are not used. Planning to provide concrete examples like
instance access (raises AttributeError) and related field access that may
bypass custom manager methods.
--
Ticket URL: <https://code.djangoproject.com/ticket/36665#comment:4>

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Segni
Type: | Mekonnen
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: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Tim Graham):

* component: Database layer (models, ORM) => Documentation

Comment:

Unless the longstanding process has recently changed without my knowledge,
the component for documentation patches that don't need code changes is
indeed "Documentation".
--
Ticket URL: <https://code.djangoproject.com/ticket/36665#comment:5>

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Segni
Type: | Mekonnen
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: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Segni Mekonnen):

PR submitted: https://github.com/django/django/pull/19962

The fix replaces the vague "tricky" language with specific examples:
- Instance access raises AttributeError (blog_instance.objects)
- Related field access may bypass custom manager methods
- Added reference to queries documentation for more details

Ready for review.
--
Ticket URL: <https://code.djangoproject.com/ticket/36665#comment:6>

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Segni
Type: | Mekonnen
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: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Jacob Walls):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36665#comment:7>

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Segni
Type: | Mekonnen
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: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Segni Mekonnen):

Hi @jacobtylerwalls, I've addressed the cross-reference and line length
issues that were causing CI failures. The documentation now explains the
base manager vs default manager distinction you mentioned, with a link to
the managers documentation. All CI checks should be passing now. Let me
know if you need any other adjustments!
--
Ticket URL: <https://code.djangoproject.com/ticket/36665#comment:8>

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Segni
Type: | Mekonnen
Cleanup/optimization | Status: assigned
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: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Jacob Walls):

* needs_better_patch: 1 => 0
* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/36665#comment:9>

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Segni
Type: | Mekonnen

Cleanup/optimization | Status: closed
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: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

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

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

Comment:

In [changeset:"b1e0262c9f9d11eae6230b51c5aa5d71122d5f05" b1e0262c]:
{{{#!CommitTicketReference repository=""
revision="b1e0262c9f9d11eae6230b51c5aa5d71122d5f05"
Fixed #36665 -- Improved manager usage guidance in
docs/topics/db/optimization.txt.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36665#comment:10>

[Django]

#36665: Rewrite reference to model manager usage to avoid saying "tricky"
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Segni
Type: | Mekonnen
Cleanup/optimization | Status: closed
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: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Jacob Walls):

Not backporting as the location of this text moved in main (6.1), and it's
only a minor edit.
--
Ticket URL: <https://code.djangoproject.com/ticket/36665#comment:11>