Opened 14 years ago

Closed 14 years ago

Last modified 13 years ago

#14000 closed (fixed)

Removal of obsolete "versionadded" tags

Reported by: Richard Barran Owned by: nobody
Component: Documentation Version: dev
Severity: Keywords: versionadded
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Attachments (4)

14000_1.diff (31.4 KB ) - added by Richard Barran 14 years ago.
First stab at removing "versionadded:: 1.0"
14000-remove-versionxxx-1.0.diff (48.9 KB ) - added by Ramiro Morales 14 years ago.
Removes occurrences of '-- version(added|changed):: 1.0'
14000-remove-versionxxx-1.0-1.2.x-branch.diff (50.5 KB ) - added by Ramiro Morales 14 years ago.
Removes ".. version*:: 1.0" stuff -- for 1.2.X branch@ r13763
14000-remove-versionxxx-1.0+1.1.diff (74.6 KB ) - added by Ramiro Morales 14 years ago.
Patch form trunk, removes version*:: 1.0 and 1.1 notes.

Download all attachments as: .zip

Change History (14)

by Richard Barran, 14 years ago

Attachment: 14000_1.diff added

First stab at removing "versionadded:: 1.0"

comment:1 by Richard Barran, 14 years ago

Has patch: set

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.

comment:2 by Ramiro Morales, 14 years ago

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

comment:3 by Richard Barran, 14 years ago

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?

comment:4 by Justin Lilly, 14 years ago

Triage Stage: UnreviewedAccepted

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.

in reply to:  3 comment:5 by Ramiro Morales, 14 years ago

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

by Ramiro Morales, 14 years ago

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

comment:6 by Ramiro Morales, 14 years ago

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'

by Ramiro Morales, 14 years ago

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

by Ramiro Morales, 14 years ago

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

comment:7 by Russell Keith-Magee, 14 years ago

milestone: 1.3

comment:8 by Tim Graham, 14 years ago

Resolution: fixed
Status: newclosed

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

comment:9 by Tim Graham, 14 years ago

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

comment:10 by Jacob, 13 years ago

milestone: 1.3

Milestone 1.3 deleted

Note: See TracTickets for help on using tickets.
Back to Top