[Django] #35772: Document models.Field.contribute_to_class

[Django]

#35772: Document models.Field.contribute_to_class
-------------------------------------+-------------------------------------
Reporter: Clifford | Owner: Clifford Gama
Gama |
Type: | Status: assigned
Cleanup/optimization |
Component: Database | Version: dev
layer (models, ORM) |
Severity: Normal | Keywords: contribute_to_class
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
In
`models/fields/__init__.py`[https://github.com/django/django/blob/9ca1f6eff6f19d1ae074d289c6c4209073351805/django/db/models/fields/__init__.py#L957-L958]
and in the
docs[https://docs.djangoproject.com/en/5.1/ref/models/instances/#django.db.models.Model.get_previous_by_FOO],
it is suggested that a user may override `Field.contribute_to_class`, but
this method is not documented anywhere in the docs. IMHO, it should find a
place here [https://docs.djangoproject.com/en/5.1/howto/custom-model-
fields/] or here [https://docs.djangoproject.com/en/5.1/ref/models/fields
/#field-api-reference] or both.
--
Ticket URL: <https://code.djangoproject.com/ticket/35772>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35772: Document models.Field.contribute_to_class
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: closed
Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution: wontfix
Keywords: contribute_to_class | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0

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

Changes (by Natalia Bidart):

* cc: James Bennett (added)
* resolution: => wontfix
* status: assigned => closed

Comment:

Hello Clifford, thank you for taking the time to create this ticket.

It took me a while to gather information to have an opinion on your
proposal. Initially it seemed like a good idea and I couldn't find
duplicated ticket reports. Then, I searched some more and found a decent
list of resources describing/talking about `contribute_to_class` (in
chronological order, and there are more):
*
[https://code.djangoproject.com/wiki/DevModelCreation#InstallingTheAttributes
Django's Wiki 2006]
* [https://lazypython.blogspot.com/2008/11/django-models-digging-little-
deeper.html Alex Gaynor's post 2008]
* [https://www.b-list.org/weblog/2019/mar/04/class/ James Bennet's post
2019]
* [https://jacobian.org/til/django-model-fields-with-attributes/ Jacob
KM's TIL 2023]

The above certainly provides great and detailed documentation about
`contribute_to_class`, and I was thinking we could borrow from those to
add to the official docs, but then I read James' post where they say:

> And now it is time for the second warning in this post:
`contribute_to_class()` is an undocumented, private, internal API. Django
does not provide backwards-compatibility guarantees for it, and if you
make use of it you accept the risk that it might change or break at any
time.

Given that, I don't think we should accept this ticket without a previous
agreement with the community. Therefore, I'll close this ticket
accordingly, and the recommended path forward would be to first propose
and discuss the idea with the community and gain consensus (perhaps
tagging James may be a good idea). To do that, please consider starting a
new conversation on the [https://forum.djangoproject.com/c/internals/5
Django Forum], where you'll reach a broader audience and receive
additional feedback.
--
Ticket URL: <https://code.djangoproject.com/ticket/35772#comment:1>

[Django]

#35772: Document models.Field.contribute_to_class
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: closed
Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution: wontfix
Keywords: contribute_to_class | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Clifford Gama):

Hello! and thank you, Natalia, for the detailed review and the community
resources on `contribute_to_class` -- they were very informative.

I'm not very much in favour of making `contribute_to_class` a part of the
public API, so I will not start a discussion in the forum for that.

However, if we agree that, as it currently stands, `contribute_to_class`
is "an undocumented, private, internal API" then I believe we should also
remove it from the docs entirely, since having it there canonises it as
part of the public API, in which case it would have to be officially
documented. Having it in there while maintaining its status as a private
part of the API is a bit in the gray area.
--
Ticket URL: <https://code.djangoproject.com/ticket/35772#comment:2>

[Django]

#35772: Document models.Field.contribute_to_class
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: closed
Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution: wontfix
Keywords: contribute_to_class | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* cc: Simon Charette, Mariusz Felisiak (added)

Comment:

Replying to [comment:2 Clifford Gama]:

> Hello! and thank you, Natalia, for the detailed review and the community
resources on `contribute_to_class` -- they were very informative.

You are welcome!

> I'm not very much in favour of making `contribute_to_class` a part of
the public API, so I will not start a discussion in the forum for that.

Right, me neither.

> However, if we agree that, as it currently stands, `contribute_to_class`
is "an undocumented, private, internal API" then I believe we should also
remove it from the docs entirely, since having it there canonises it as
part of the public API, in which case it would have to be officially
documented. Having it in there while maintaining its status as a private
part of the API is a bit in the gray area.

I half-agree with this. I do think that it's weird to mention something in
the public docs that is not public, but at the same time, providing that
pointer could be very useful for some very specific cases.

My proposal to go to the forum can instead be repurposed to ask for
feedback about removing the reference, or leaving it as is, un-referenced?
--
Ticket URL: <https://code.djangoproject.com/ticket/35772#comment:3>

[Django]

#35772: Document models.Field.contribute_to_class
-------------------------------------+-------------------------------------
Reporter: Clifford Gama | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: closed
Component: Database layer | Version: dev
(models, ORM) |
Severity: Normal | Resolution: wontfix
Keywords: contribute_to_class | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Clifford Gama):

> I half-agree with this. I do think that it's weird to mention something
in the public docs that is not public, but at the same time, providing
that pointer could be very useful for some very specific cases.

I agree. However, I’m not sure that the current approach is the best way
to handle it. When something is mentioned in the documentation, you expect
that either it's explained there or at least linked to further details.
That said, I don’t have an immediate solution either.

> My proposal to go to the forum can instead be repurposed to ask for
feedback about removing the reference, or leaving it as is, un-referenced?

Yes, I'll open up a discussion on this, but I’ll hold off until after I’ve
put together a draft PR for #27880, which is tied up with
`contribute_to_class`.
--
Ticket URL: <https://code.djangoproject.com/ticket/35772#comment:4>