Document models.Field.contribute_to_class

[Clifford Gama]

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.

[Natalia Bidart]

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):

• Django's Wiki 2006
• ​Alex Gaynor's post 2008
• ​James Bennet's post 2019
• ​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 ​Django Forum, where you'll reach a broader audience and receive additional feedback.

[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.

[Natalia Bidart]

Replying to 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?

[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.