Field.primary_key documentation should details its interaction with CompositePrimaryKey

[Simon Charette]

A particular focus should be put on the fact that the flag will and should only be set to True if the field is the single member of the primary key. When a composite primary is defined on the model this flag will be False for all the fields defined on the model and _meta.pk_fields (which should be documented) should be used instead to build composite primary key ready third-party application.

In other words, it should be made clear that code that relies solely on Field.primary_key is not composite primary key ready and that _meta.pk_fields should be used instead. I feel like this is something that should be clearly pointed out in the composite primary key documentation on how to make reusable app code composite primary key ready.

[Sarah Boyce]

From #36074

If you grep for .primary_key you'll notice that most of the checks against this field need to be adjusted to use field in opts.pk_fields instead which makes me wonder if we took the right decision by not setting this flag to True when included as a member of CompositePrimaryKey.

I am not sure how best to reword the title but I think this piece of work (checking the existing checks against the primary_key attribute and whether they should be using field in opts.pk_fields, as well as checking the decision to not setting this flag to True when included as a member of CompositePrimaryKey) could be part of this ticket, as this documentation should accompany those changes.

[Simon Charette]

Sleeping on it I think it's fine that we keep things as they are code wise on the assignment of primary_key = False when used with CompositePrimaryKey as long as we clearly document that _meta.pk_fields should be used. The reason is that many of the field.primary_key usages immediately stop when they first their first match so they are likely broken anyway.

Forcing third-party applications that wish to support composite primary keys to migrate to _meta.pk_fields and abandon .primary_key seem like a better option that having code implicitly break because they only expect one field to have primary_key = True which is decade old assumption.