Opened 10 years ago

Closed 10 years ago

Last modified 9 years ago

#8991 closed (wontfix)

Remove "version[added|changed]" from trunk docs

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


Just as a reminder, I'm doing the patch ;)

Attachments (1)

django.git-docs-trunk.patch (60.2 KB) - added by Marc Fargas 10 years ago.

Download all attachments as: .zip

Change History (8)

comment:1 Changed 10 years ago by Marc Fargas

Owner: changed from nobody to Marc Fargas
Status: newassigned

Changed 10 years ago by Marc Fargas

Attachment: django.git-docs-trunk.patch added


comment:2 Changed 10 years ago by Marc Fargas

Triage Stage: UnreviewedAccepted

Here it goes, note that the patch also changes a part of contributing.txt clarifying the "version[added|changed]" thing a bit more. (That patch is a diff of my docs branch so that came with the diff...)

Hope it's ok. As always, up-to-date diff without conflicts (hopefully) on my git tree

comment:3 Changed 10 years ago by Julian Bez

Why is it going to be removed?

comment:4 Changed 10 years ago by Marc Fargas

Because documentation is not a Version Control System, those notes are meant to be kept so you know what's new in a given version, but keeping them all the way can lead to an unmanegeable documentation (i.e.: Paragraphs added to explain changes from X.Y to X.Z, etc) it's up to every project to decide how many of those to keep, and wich ones.

It's just a matter of preference, it's mostly up to Jacob to decide how to treat the version[added|changed] stuff.

I personally would prefer to remove everything pre-1.0, and on 1.1 leave the notes that make sense to stay until 1.2 (i.e. deprecated features (versionchanged) should stay in docs until they are completely dropped).

comment:5 Changed 10 years ago by Marc Fargas

Resolution: wontfix
Status: assignedclosed

As per IRC, it's prefered to keep those strings not excluding rewritting docs parts for better styling as long as the "When was this added/changed" is still there.

comment:6 Changed 10 years ago by Jacob

FTR, this is what I told teleniko on IRC: These directives are there for a reason: the docs get better over time, but people don't always upgrade to newer releases. So I want to leave 'em so that folks reading newer docs don't get (too) confused.

comment:7 Changed 9 years ago by (none)

milestone: post-1.0

Milestone post-1.0 deleted

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