Ticket #9321 -- Modelform widgets help text for ManyToMany fields

[Ramiro Morales]

Hi all,

This is a proposal for fixing this small and old issue
(https://code.djangoproject.com/ticket/9321):

Model forms for models that include a ManyToMany field get a hard-coded

"*Hold down "Control", or "Command" on a Mac, to select more than one."

sentence in the respective help text

This sentence can be either:
a) Forced as the HTML field help text if the user didn't provide a
help_text or
b) Appended to the user's one.

Emphasis should be put on the fact that this only affects:

* Model forms
* ...for models with at least one m2m field
* ...for which custom form fields/widgets are being used where the user
interaction doesn't actually involve using a visual selection
expandable by mouse click and key presses combinations. Or designs
where the developer simply doesn't want that string appearing on their
form at all.

The proposed fix is somewhat simple (I'd say trivial) compared
to the ones proposed so far and has the following implementation
timeline:

Django 1.6:
Stop hard-coding this at the model level. Still do that at the form
field level (ModelMultipleChoiceField) but only for field instances that
are paired to a (subclass of) SelecMultiple widget.

This has the net effect that we stop forcing the hard-coded string on
every kind of form field for m2ms (the main complaint and the actual
fix of the issue at hand).

This could impact custom m2m field form fields/widgets that don't
inherit from SelectMultiple with a previously unannounced
backward-incompatible change if they rely on the help_text munging
performed by the ORM field, but OTOH would keep the greater audience
(those who use the default widgets or use a subclass of SelectMultiple
for which the hard-coded help text is relevant/useful e.g. the admin)
safe by not changing anything at all for them.

Django 1.7:
Simply stop forcing the hard-coded sentence. If users want to have it
set or added to their help text they should provide it by themselves
just like it happens with every other [model] form field.
These users are in a better position to know if it is relevant to the form
widget in use.

This deprecation cycle won't be implemented using
[Pending]DeprecationWarning's, but rather by only documentation. The
release notes and backward incompatible timeline entry for 1.6 would
warn about the changes coming in 1.7 so they can act in advance.

Reasoning for this is that we would be forced to detect field/widget
subclassing to be able to catch the cases where warnings should be
triggered and these warnings could get noisy fast. IMHO this isn't worth
the trouble.

What do you think?

Also, WIP PR: https://github.com/ramiro/django/compare/master...9321-m2m-help_text
(only piece missing is the warnings described in the last two paragraphs.)

--
Ramiro Morales
@ramiromorales

[Ramiro Morales]

On Sat, May 18, 2013 at 11:38 PM, Ramiro Morales <cra...@gmail.com> wrote:
> Hi all,
>
> This is a proposal for fixing this small and old issue
> (https://code.djangoproject.com/ticket/9321):
>

> [...]

>
> Django 1.7:
> Simply stop forcing the hard-coded sentence. If users want to have it
> set or added to their help text they should provide it by themselves
> just like it happens with every other [model] form field.
> These users are in a better position to know if it is relevant to the form
> widget in use.
>
> This deprecation cycle won't be implemented using
> [Pending]DeprecationWarning's, but rather by only documentation. The
> release notes and backward incompatible timeline entry for 1.6 would
> warn about the changes coming in 1.7 so they can act in advance.
>

> [...]

>
> Also, WIP PR: https://github.com/ramiro/django/compare/master...9321-m2m-help_text
> (only piece missing is the warnings described in the last two paragraphs.)

I've updated the branch to add such documentation warnings. Also, changed
the timeline to extend over two release cycles (1.6 - 1.8) instead of
accelerating it to finish in 1.7.

I've also created a second branch with the changes that would need to be
performed before releasing 1.8:

https://github.com/ramiro/django/compare/9321-m2m-help_text...9321-m2m-help_text-post-1.6

Apps now need to take care of the help text, the admin app is one of
them and so does this patch by moving the logic there.

Note how tests that check the HTML output of modelforms for models with
m2m fields don't need to contain the non-relevant help text markup
anymore.

Regards,

--
Ramiro Morales
@ramiromorales