documentation bug for base managers

[David Gudeman]

The documentation (​https://docs.djangoproject.com/en/2.2/topics/db/managers/#base-managers) for "Managers->Base managers" seems to contradict itself:

para 1, line 1: "By default, Django uses an instance of the Model._base_manager manager class when accessing related objects"

para 3, line 1: "Base managers aren’t used when querying on related models."

This is reinforced with an example in para 3, but is then (apparently) contradicted again:

para 4, line 1: "This manager is used to access objects that are related to from some other model."

Furthermore, para 3 give an example of a base model that filters out some rows and then in the next section we get a scary-sounding warning not to do that or bad things will happen. But the scary warning is odd because it seems to be warning me that it will do exactly what I intend it to do. If I use the example from para 3, then I *want* it to filter out deleted rows. Why is that bad? And especially, why is it bad when para 3 says it won't work anyway?

Finally, para 1 and 2 seem to say that to change Model._base_manager I should change Meta.base_manager_name, but doesn't say what the difference it makes.

[Carlton Gibson]

Grrr... Hi David.

Can I first say, you pretty much want to forget this bit of the docs exists — unless you're super sure what you're doing, and even then, leave _base_manager well alone. (TBH not sure why it's documented the _ prefix implies private method... — NoteToSelf: should look up why it's documented)

The key point is that the .filter(question__name__startswith) bit, as a query, will use Question._default_manager even though the choice.question lookup, as a direct access, will use _base_manager.

Have a read of (some of) ​`django/db/models/fields/related_descriptors.py` to see where _base_manager is used in this way. (Imagine you have a foreign key to an object filtered by _default_manager 💥...)

I'm not sure this is really addressable. Bar a big warning banner saying "Here be dragons" I don't think there's much we can do to clarify this. (But concrete suggestions always to be considered...)