Point users to BoundField.initial instead of Form.get_initial_for_field()

[Chris Jerdonek]

Currently, the documentation ​points users to Form.get_initial_for_field(field, field_name) to get the initial data for a form field. However, I think it would be better to point users to BoundField.initial (​link to code), e.g. using the pattern form[field_name].initial. (BoundField.initial should also be added to the ​BoundField attribute documentation, as it seems to have been left out.)

There are a couple reasons I think users should be steered away from get_initial_for_field(). One reason is that BoundField's API is simpler because it doesn't require passing redundant field and field_name arguments. Another reason is that going through BoundField has the advantage of using the BoundField instance's cache, as initial is a cached property. (I'm going to be filing another ticket related to the latter difference, later.)

[Chris Jerdonek]

PR: ​https://github.com/django/django/pull/14651

[Carlton Gibson]

#32937 brought up that whilst Form.get_initial_for_field() doesn't cache its return values, whereas ​BoundField.initial does.

Discussion there was to...

... add a paragraph in ​​https://docs.djangoproject.com/en/3.2/ref/forms/api/#dynamic-initial-values saying _Why_ BoundField.initial is preferred: simpler interface, and caches values, which matters for callables, like now().

That can be resolved as part of this ticket.

[Carlton Gibson <carlton.gibson@…>]

In 6559a55:

Fixed #32933 -- Documented BoundField.initial as preferred over Form.get_initial_for_field().

[Carlton Gibson <carlton.gibson@…>]

In aace6c53:

[3.2.x] Fixed #32933 -- Documented BoundField.initial as preferred over Form.get_initial_for_field().

Backport of 6559a55eed09780b30ee3c3636ccf30318622bcf from main