[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Fred L. Drake, Jr.]

Fred L. Drake, Jr. added the comment:

For anyone following along only via the tracker, it's worth noting that 
proposals for new markup are welcome on the docs mailing list.  More 
information is available at:

https://mail.python.org/mailman/listinfo/docs

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Raymond Hettinger]

Raymond Hettinger added the comment:

Fred, thanks for chiming in.  Let's do close this one.

--
nosy: +rhettinger
resolution:  -> not a bug
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Fred L. Drake, Jr.]

Fred L. Drake, Jr. added the comment:

If no one is planning to propose specific new markup for more fine-grained 
version annotations, this issue can be closed.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Fred L. Drake, Jr.]

Fred L. Drake, Jr. added the comment:

Another reason to value the status-quo in this case is that this isn't just
a matter for the Python documentation; it's about the recommended usage for
the markup, which is used by many other packages.

Questions that should be discussed include:

1. Should we clarify the documentation for the current annotations to
   the intended use is more consistently understood, or should we leave
   it as-is?

2. Are other distinct kinds of annotations (such as per-parameter notes)
   needed?

   If so, we'll need to consider specific reader / information-content
   needs and determine how they should be marked using new constructs.

   This is independent of implementation, which is likely straightforward.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Tony R.]

Tony R. added the comment:

> Part of the problem is getting the granularity right.  The initial intent was
> that 'version*' were annotations for the enclosing object (function, class,
> method, etc.).  If we want to have something more granular (parameter
> added / deprecated / whatever), we should have distinct markup for that.
> 
> That could look something like:
> 
> .. parameteradded:: alternate 3.6
>Further explanation goes here.
> 
> It's helpful to think of these annotations as pronouns; the antecedent
> needs to be clear before they can be interpreted correctly.

Isn’t language fun?!?!  *insane smile* 8)

> It sounds
> like that needs to be clarified in the documentation, and possibly
> provision added for a more fine-grained form of annotation.

Okay.  I can participate in the discussion of that, if it would help...but 
adding a completely new annotation type is outside my current ability to 
contribute.  




> > Well then, if this is the sort of place where the status quo is sacred,
> > then there is nothing more to discuss.  
> 
> That wasn't my intention when quoting the old documenting guide, it was just
> to show what the intent was (and still is), and that I didn't just invent it.

Your intent was clear to me!  I did not mean to say that you -- or anyone -- 
just invented it.  

I only know that mature projects (like Python) tend to hold more strongly to 
the status quo, and that I was advocating a change that was probably going to 
be an uphill battle to convince others as worthwhile.

> That's a nice strawman -- we all feel semantic markup is important, and we
> are talking about nothing but semantic markup here.  We're just discussing
> the interpretation of one aspect of the semantics.

It was not my wish to set up a strawman.  (I have no formal training in logic, 
anyways; I’d probably screw it up if I deliberately tried!)  

The reason I was stressing semantic markup is because I anticipated resistance 
from the mindset of “Ugh, I don’t want to deal with this tedious crap!”  I  
wanted to emphasize semantic markup as something valuable -- worth making an 
effort for, even if it might appear tedious or trivial at first glance.  



That said, I think it’s time for me to bow out of this conversation.  I’ve 
never made a successful contribution to any part of Python, including the 
documentation.  There was some talk of updating the devguide or adding new 
annotations, so I hope that something good comes out of that!  But the issue 
patch is where my comfort level is right now, and it appears that it’s a no-go.

Thank you for your time, your consideration, and the discussion!

—Tony

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Georg Brandl]

Georg Brandl added the comment:

> Well then, if this is the sort of place where the status quo is sacred,
> then there is nothing more to discuss.  

That wasn't my intention when quoting the old documenting guide, it was just
to show what the intent was (and still is), and that I didn't just invent it.
As Fred says, the status quo is not sacred, but we are usually pragmatic and
a nontrivial amount of weight is needed to change it.

> But if anyone reading this is open to the idea, please re-read my previous
> comment in this thread.  The quoted LaTeX docs are clear, but I still
> believe my “all changes = (deprecated-removed changes) + (added changes) +
> (other changes)” interpretation makes more sense than the LaTeX definition.

It's one interpretation, yes.  My interpretation (which coincides with the one
written back then by Fred) is that the versionchanged applies to the API item
in whose block it occurs.  And a function is not *added* by the addition of
a parameter, it is *changed* by that.  The parameter itself is not a marked-
up API item.  If the structure was like

.. function:: foo(a, b)
   .. parameter:: a
   .. parameter:: b

then adding a parameter c would definitely be marked up as

   .. parameter:: c
  .. versionadded: 3.x

Anyway.  You think your interpretation is better, others including myself
prefer the current one.  This is exactly the kind of argument where the 
status quo wins because the churn necessary to change is not justified.

> It’s not my desire to be troublesome by making one more appeal.  I simply
> want to point out that just because somebody wrote the LaTeX definitions a
> long time ago doesn’t mean that we cannot rewrite them.  They were written
> by somebody just like us, after all.  

Again, you're mistaking the reason I quoted them.

> If it’s not obvious by now, I feel strongly about good semantic markup.
> The purpose of semantic markup is to describe what something *is*. I just
> think that changes form a hierarchy, with a generic “change” as something
> of the base class, and “deprecated”, “removed”, and “added” as 
> specializations.

That's a nice strawman -- we all feel semantic markup is important, and we
are talking about nothing but semantic markup here.  We're just discussing
the interpretation of one aspect of the semantics.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Fred L. Drake, Jr.]

Fred L. Drake, Jr. added the comment:

On Fri, Feb 19, 2016 at 10:02 AM, Tony R.  wrote:
> Holy crap!  You all used to use LaTeX?!  :D

Python's documentation has a long & colorful history.  :-)

> Well then, if this is the sort of place where the status quo is sacred, then
> there is nothing more to discuss.

Status quo is not sacred, but does have some value.  Changing how busy
people do things is non-trivial.

> But if anyone reading this is open to the idea, please re-read my previous
> comment in this thread.  The quoted LaTeX docs are clear, but I still
> believe my “all changes = (deprecated-removed changes) + (added
> changes) + (other changes)” interpretation makes more sense than the
> LaTeX definition.
>
> I also think it is more helpful to the *reader*--which, I respectfully 
> suggest,
> should be the basis for any documentation’s guidelines--by marking up
> changes according to this grouping.

I think we all agree that the documentation is for the reader.

> It’s not my desire to be troublesome by making one more appeal.
> I simply want to point out that just because somebody wrote the
> LaTeX definitions a long time ago doesn’t mean that we cannot
> rewrite them.  They were written by somebody just like us, after all.

As the person who wrote them, I don't consider them sacred or
unchangeable.

Having some rational basis for whatever we use is good, and it should
be clearly documented clearly.

> If it’s not obvious by now, I feel strongly about good semantic markup.

We're on the same page here.

> The purpose of semantic markup is to describe what something *is*.
> I just think that changes form a hierarchy, with a generic “change” as
> something of the base class, and “deprecated”, “removed”, and “added”
> as specializations.

Again, agreed.  That doesn't imply that the specializations encompass
all changes, though.  For some, 'versionchanged' is reasonable.

Part of the problem is getting the granularity right.  The initial intent was
that 'version*' were annotations for the enclosing object (function, class,
method, etc.).  If we want to have something more granular (parameter
added / deprecated / whatever), we should have distinct markup for that.

That could look something like:

.. parameteradded:: alternate 3.6
   Further explanation goes here.

It's helpful to think of these annotations as pronouns; the antecedent
needs to be clear before they can be interpreted correctly.  It sounds
like that needs to be clarified in the documentation, and possibly
provision added for a more fine-grained form of annotation.

  -Fred

--
nosy: +fdrake
title: Use “.. versionadded” over “.. versionchanged” where appropriate -> Use 
“.. versionadded” over “.. versionchanged” where appropriate

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Tony R.]

Tony R. added the comment:

> Here are the original descriptions of the old LaTeX version.

Holy crap!  You all used to use LaTeX?!  :D  

(I know--LaTeX is still going strong in academia.  I just had no idea it was 
ever part of Python’s documentation, except as an output format.)

> Adding a parameter is explicitly a "versionchanged" kind of change.
> 
> Since the Sphinx items are supposed to be equivalent, this has always been 
> the intention, even if the current devguide deviates.

Ah, okay.  

Well then, if this is the sort of place where the status quo is sacred, then 
there is nothing more to discuss.  

But if anyone reading this is open to the idea, please re-read my previous 
comment in this thread.  The quoted LaTeX docs are clear, but I still believe 
my “all changes = (deprecated-removed changes) + (added changes) + (other 
changes)” interpretation makes more sense than the LaTeX definition.  

I also think it is more helpful to the *reader*--which, I respectfully suggest, 
should be the basis for any documentation’s guidelines--by marking up changes 
according to this grouping.

It’s not my desire to be troublesome by making one more appeal.  I simply want 
to point out that just because somebody wrote the LaTeX definitions a long time 
ago doesn’t mean that we cannot rewrite them.  They were written by somebody 
just like us, after all.  

If it’s not obvious by now, I feel strongly about good semantic markup.  The 
purpose of semantic markup is to describe what something *is*. I just think 
that changes form a hierarchy, with a generic “change” as something of the base 
class, and “deprecated”, “removed”, and “added” as specializations.

If you’re reading this, and you feel similarly--speak up!  

What do you think?


Respectfully,

—Tony

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Tony R.]

Tony R. added the comment:

> My weak opinion is that a new parameter is a new API item, not just a change 
> in behaviour, so should probably have “versionadded”. 

This was my reasoning as well.  

Also, when I noticed so many instances of ``.. versionchanged`` that all say 
“Added the *x* parameter” (or whatever), it strikes me that these are a *large 
class of changes*, which all have some kind of addition in common.  If you 
think about it, deprecations and removals are also changes, but they are a 
large-enough class of changes to merit a distinct markup directive.  

So, just as this is true for “deprecated” or “deprecated-removed”, I believe it 
is just as true for “added”.  Once all additions, deprecations, and removals 
have been marked up as such, I think find that there’s still PLENTY of 
annotations that remain under ``.. versionchanged``.  

Put another way: 

Since these are all different types of changes, it is most useful to the reader 
if the most specific *type* of change is reflected in the markup.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Berker Peksag]

Berker Peksag added the comment:

I agree with Georg and Ezio. We should update the devguide.

Tony, would you like to propose a patch? The repo is at 
https://hg.python.org/devguide

--
nosy: +berker.peksag

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Martin Panter]

Martin Panter added the comment:

If you changed existing versionadded notices to versionchanged in similar 
cases, how would the size of the patch compare? This problem was also recently 
brought up at 
.

My weak opinion is that a new parameter is a new API item, not just a change in 
behaviour, so should probably have “versionadded”. But I hardly think it is a 
big problem whichever markup is used.

--
nosy: +martin.panter

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Georg Brandl]

Georg Brandl added the comment:

The devguide should be updated, yes.

And probably someone should look at the remaining versionadded's...

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Ezio Melotti]

Ezio Melotti added the comment:

I agree with Georg.
I also went to double-check what the devguide says, and at 
https://docs.python.org/devguide/documenting.html#paragraph-level-markup it 
shows an example of versionadded for a parameter.
If a versionchanged should be used instead, maybe the devguide should be fixed.

Having versionadded/changed used consistently would also be nice though, 
especially if we can start exploiting them (together with 
deprecated/deprecated-removed) to auto-generate sections of the whatsnew page.

--
nosy: +ezio.melotti

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Georg Brandl]

Georg Brandl added the comment:

Hi Tony,

thanks for the patch, and for the will to contribute.  I'm not sure this patch 
should be merged though; the original intention was to use "versionadded" where 
the API item is completely new.  So "The parameter x was added" in a function 
is using "versionchanged" because only an aspect of the function's signature 
was changed.

There may be a bit of confusion because many people wrote changes, and not 
every change is reviewed by the same developers, but this is the original 
intent that I think we should not change wholesale.

--
nosy: +georg.brandl

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Tony R.]

New submission from Tony R.:

In the documentation, I noticed several uses of ``.. versionchanged::`` that 
described things which had been added.  

I love Python, and its documentation, and I wanted to contribute.  So, I 
figured a low-risk contribution would be to change ``.. versionchanged::`` to 
“.. versionadded” where appropriate.  (I also tweaked the descriptions 
accordingly.  E.g., “Added the *x* argument” became “The *x* argument”, because 
it’s unnecessary to say “added” in a description under “.. versionadded”.)

I did also make a few unrelated tweaks along the way--all very minor, and 
related to phrasing or formatting. 

Please let me know if I can do anything else to get this merged!

--
assignee: docs@python
components: Documentation
files: _docs-version-markup.patch
keywords: patch
messages: 260313
nosy: Tony R., docs@python
priority: normal
severity: normal
status: open
title: Use “.. versionadded” over “.. versionchanged” where appropriate
type: enhancement
Added file: http://bugs.python.org/file41929/_docs-version-markup.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com