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!

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.

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.

The devguide should be updated, yes.

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

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 <https://bugs.python.org/review/19475/diff/16235/Doc/library/datetime.rst#newcode1180>.

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.

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

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

Here are the original descriptions of the old LaTeX version.

    \begin{macrodesc}{versionadded}{\op{explanation}\p{version}}
      The version of Python which added the described feature to the
      library or C API.  \var{explanation} should be a \emph{brief}
      explanation of the change consisting of a capitalized sentence
      fragment; a period will be appended by the formatting process.
      When this applies to an entire module, it should be placed at
      the top of the module section before any prose.
    \end{macrodesc}

    \begin{macrodesc}{versionchanged}{\op{explanation}\p{version}}
      The version of Python in which the named feature was changed in
      some way (new parameters, changed side effects, etc.).
      \var{explanation} should be a \emph{brief} explanation of the
      change consisting of a capitalized sentence fragment; a
      period will be appended by the formatting process.  This should
      not generally be applied to modules.
    \end{macrodesc}

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.

> 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

On Fri, Feb 19, 2016 at 10:02 AM, Tony R. <report@bugs.python.org> 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

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

> 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

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.

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

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

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