> Another documentation-related question I have; is it necessary to mark
> each passing referencing (and link) to on_delete with the version-
> added marker? I went back and forth, and eventually decided against
> it, for these reasons: (1) The passing references don't provide enough
> info to use the feature; anyone following the link to the actual
> feature documentation will see the version marker, and (2) inserting
> the version-added markers in places like the QuerySet.delete
> documentation made it appear ambiguous to me exactly which paragraphs
> the marker referred to; it would be a reasonable interpretation to
> think it covered everything through the end of the section, which
> would not be accurate. Open to feedback from the documentation experts
> here.
As much as I'd like to agree that the "versionadded" directives aren't
needed for the sake of not adding clutter, I have no doubt that within
weeks we'd have someone opening a ticket because they tried to use the
on_delete argument with a previous release, not realizing they were
looking at the dev/1.3 docs. So here's my recommendation:
1. Add the versionadded directive to "docs/topics/db/queries.txt", and
"docs/ref/contrib/contenttypes.txt". For reference, you can make it
very clear what was changed/added by using the following syntax (note
the *single* line break between the versionadded and the following
*indented* text):
.. versionadded:: 1.3
The on_delete attribute was [blah blah blah...]
Thus the ambiguity about whether this paragraph or that paragraph was
changed can be avoided.
2. The documentation for "docs/ref/models/querysets.txt" needs to have
a versionadded directive as well, however the bulk of that text needs
to be backported to the 1.2.X docs, as per #14599 [1], and the
backported text shouldn't have any reference to on_delete at all.
It looks like an excellent patch overall. Thanks to everyone involved!
- Gabriel
[1] http://code.djangoproject.com/ticket/14599
--
You received this message because you are subscribed to the Google Groups
"Django developers" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/django-developers?hl=en.
