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 Jacob Walls, 23 hours ago

Component: Database layer (models, ORM)Documentation

comment:2 by Natalia Bidart, 22 hours ago

Component: DocumentationDatabase layer (models, ORM)
Triage Stage: UnreviewedAccepted

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.

comment:3 by Jacob Walls, 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 Segni Mekonnen, 19 hours ago

Has patch: set
Owner: set to Segni Mekonnen
Status: newassigned

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 Tim Graham, 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 Segni Mekonnen, 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 Jacob Walls, 3 hours ago

Patch needs improvement: set
Note: See TracTickets for help on using tickets.
Back to Top