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

Tony R. report at bugs.python.org
Thu Feb 18 11:27:57 EST 2016

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 <report at bugs.python.org>

More information about the docs mailing list