Opened 23 hours ago
Last modified 3 hours ago
#36665 assigned Cleanup/optimization
Rewrite reference to model manager usage to avoid saying "tricky"
Reported by: | Jacob Walls | Owned by: | Segni Mekonnen |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Normal | Keywords: | |
Cc: | Triage Stage: | Accepted | |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | yes |
Easy pickings: | no | UI/UX: | no |
Description
In the 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.)
Change History (7)
comment:1 by , 23 hours ago
Component: | Database layer (models, ORM) → Documentation |
---|
comment:2 by , 22 hours ago
Component: | Documentation → Database layer (models, ORM) |
---|---|
Triage Stage: | Unreviewed → Accepted |
comment:3 by , 21 hours ago
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 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.
comment:4 by , 19 hours ago
Has patch: | set |
---|---|
Owner: | set to |
Status: | new → assigned |
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.
comment:5 by , 16 hours ago
Component: | Database layer (models, ORM) → Documentation |
---|
Unless the longstanding process has recently changed without my knowledge, the component for documentation patches that don't need code changes is indeed "Documentation".
comment:6 by , 4 hours ago
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.
comment:7 by , 3 hours ago
Patch needs improvement: | set |
---|
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.