Removal of obsolete "versionadded" tags

[Richard Barran]

The Django documentation places a strong emphasis on highlighting new/changed features with lines such as:

"New in Django 1.0: Please, see the release notes"

However, these tags become cruft once they start referring to obsolete versions of Django.
Please see this thread on django-dev for more: ​http://groups.google.com/group/django-developers/browse_thread/thread/4b7a5a471cdd66fc

There is in the documentation:

• For version 1.0: 252 'versionadded' and 50 'versionchanged'.
• For version 1.1: 142 'versionadded' and 26 'versionchanged'.

Version 1.0 tags can certainly go - but not sure about tags for 1.1?

Note: I'll post an initial patch in a few hours time.

[Richard Barran]

First stab at removing "versionadded:: 1.0"

[Richard Barran]

Added patch 14000_1.diff: this is a first stab at removing references to 'versionadded' (100 references removed).
I deliberately restricted myself to simple, straightforward removals e.g.:

• new attributes or methods or settings with a "New in 1.0" label.
• new features with a "New in 1.0" label.

I've kept away so far from cases where new behaviour is being documented; some of these could use a re-write in order to fully integrate the "new feature" section with the rest of the text.

[Ramiro Morales]

I'm testing an script that automatize this kind of replacements using some old code I used when working on the translation of the Django book. Figured it'd be an useful addition to the toolbox located in docs/_ext/ so it can be used to do the grunt part of the work not only now but on future releases (e.g. run it with a '1.1' command line argument before Django 1.4 is released *).

So far, it does this when removing '.. version(added|changed):: 1.0' stuff:

 howto/custom-management-commands.txt  |    2 --
 howto/custom-model-fields.txt         |    1 -
 howto/custom-template-tags.txt        |    5 -----
 howto/deployment/modpython.txt        |    1 -
 ref/contrib/flatpages.txt             |    2 --
 ref/contrib/formtools/form-wizard.txt |    2 --
 ref/contrib/gis/index.txt             |    2 --
 ref/contrib/humanize.txt              |    2 --
 ref/contrib/index.txt                 |    1 -
 ref/contrib/sitemaps.txt              |    2 --
 ref/contrib/sites.txt                 |    4 ----
 ref/databases.txt                     |    2 --
 ref/django-admin.txt                  |   10 ----------
 ref/forms/api.txt                     |    3 ---
 ref/forms/fields.txt                  |   12 ------------
 ref/forms/widgets.txt                 |    2 --
 ref/generic-views.txt                 |    8 --------
 ref/middleware.txt                    |    3 ---
 ref/models/fields.txt                 |   15 ---------------
 ref/models/instances.txt              |    5 -----
 ref/models/options.txt                |    4 ----
 ref/models/querysets.txt              |   23 -----------------------
 ref/request-response.txt              |   14 --------------
 ref/settings.txt                      |   30 ------------------------------
 ref/templates/api.txt                 |    2 --
 ref/templates/builtins.txt            |   20 --------------------
 ref/unicode.txt                       |    2 --
 releases/1.0.txt                      |    1 -
 topics/auth.txt                       |    7 -------
 topics/cache.txt                      |    9 ---------
 topics/db/models.txt                  |    8 --------
 topics/db/queries.txt                 |    4 ----
 topics/email.txt                      |    2 --
 topics/files.txt                      |    2 --
 topics/forms/index.txt                |    1 -
 topics/forms/modelforms.txt           |    2 --
 topics/http/file-uploads.txt          |    2 --
 topics/http/sessions.txt              |   23 -----------------------
 topics/http/shortcuts.txt             |    2 --
 topics/http/urls.txt                  |    4 ----
 topics/i18n/deployment.txt            |    2 --
 topics/pagination.txt                 |    3 ---
 topics/templates.txt                  |    2 --
 topics/testing.txt                    |   18 ------------------
 44 files changed, 271 deletions(-)

Visual inspection shows additional 31 hand editions are needed after this as well to remove paragraphs that talk about the changes in 1.0 and are left orphan.

Will upload it once I clean it up a bit.

• I suspect I have my numbers mixed/shifted here because now 1.2 has been released, the window of supported releases would be 1.2 and 1.1 so we would need to have removed all the 'version(added|changed): 1.0' notes in the 1.2 docs and would need to do the same with the notes for 1.1 before 1.3 gets released.

But I suspect core devs won't want to make such an invasive modification to the docs on the 1.2.x branch at this point (although OTOH doing so would the risk of conflicts when backporting doc patches from trunk).

[Richard Barran]

Hi Ramiro,

I would be interested in seeing your script once it's cleaned up!

I had thought of automating the removal of these tags, but got worried about it cutting out too much. For example, if you look at ​http://docs.djangoproject.com/en/1.2/ref/models/querysets/#order-by-fields there are several "comments" added on with a versionadded tag, if you just remove the tag then the document would no longer flow naturally and would be difficult to read.

After spending a couple of hours manually stripping out tags (and posting the patch here) I realised that the majority of the tags are in fact attached to new attributes, methods, or settings, and so it should be possible to automatically detect these tags and remove only these, leaving the rest for manual review. Does your script do this?

By the way, I notice that your script says it's removing 2 tags from ref/contrib/flatpages.txt and also from ref/contrib/formtools/form-wizard.txt - but I can only find one tag in the source for each of those pages?

[Justin Lilly]

I think its important to not just remove the version added tags, but reflow them into the text. The "versionadded" bits tend to come at the end of the section rather than where it would naturally come in the text.

[Ramiro Morales]

Replying to richardb:

By the way, I notice that your script says it's removing 2 tags from ref/contrib/flatpages.txt and also from ref/contrib/formtools/form-wizard.txt - but I can only find one tag in the source for each of those pages?

Sorry, what I had posted is the output of diffstat that works in a line-wise fashion. When it says there are two changes it is because the script removed a '.. versionadded:: 1.0' line and the empty line below it (if any).

[Ramiro Morales]

Removes occurrences of '-- version(added|changed):: 1.0'

[Ramiro Morales]

Last attached patch removes only the notes about 1.0 for now (trunk, r13746). 150 automatic deletions replacements plus 36 manual editions after visual inspection of the resulting thunks and grepping for '1.0'

[Ramiro Morales]

Removes ".. version*:: 1.0" stuff -- for 1.2.X branch@ r13763

[Ramiro Morales]

Patch form trunk, removes version*:: 1.0 and 1.1 notes.

[Tim Graham]

(In [15055]) Fixed #14000 - remove versionadded/changed tags for Django 1.0 and 1.1

[Tim Graham]

(In [15056]) [1.2.X] Fixed #14000 - Remove versionadded/changed tags for 1.0. thanks ramiro!

[Jacob]

Milestone 1.3 deleted