Opened 5 years ago

Closed 5 years ago

Last modified 4 years ago

#14000 closed (fixed)

Removal of obsolete "versionadded" tags

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

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 richardb 5 years ago.
First stab at removing "versionadded:: 1.0"
14000-remove-versionxxx-1.0.diff (48.9 KB) - added by ramiro 5 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 5 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 5 years ago.
Patch form trunk, removes version*:: 1.0 and 1.1 notes.

Download all attachments as: .zip

Change History (14)

Changed 5 years ago by richardb

First stab at removing "versionadded:: 1.0"

comment:1 Changed 5 years ago by richardb

  • Has patch set
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

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 Changed 5 years ago by ramiro

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 follow-up: Changed 5 years ago by richardb

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 Changed 5 years ago by justinlilly

  • Triage Stage changed from Unreviewed to Accepted

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.

comment:5 in reply to: ↑ 3 Changed 5 years ago by ramiro

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

Changed 5 years ago by ramiro

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

comment:6 Changed 5 years ago by ramiro

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'

Changed 5 years ago by ramiro

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

Changed 5 years ago by ramiro

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

comment:7 Changed 5 years ago by russellm

  • milestone set to 1.3

comment:8 Changed 5 years ago by timo

  • Resolution set to fixed
  • Status changed from new to closed

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

comment:9 Changed 5 years ago by timo

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

comment:10 Changed 4 years ago by jacob

  • milestone 1.3 deleted

Milestone 1.3 deleted

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