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

Tony R. report at bugs.python.org
Fri Feb 19 12:21:05 EST 2016

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!



Python tracker <report at bugs.python.org>

More information about the docs mailing list