[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 <report at bugs.python.org>
<http://bugs.python.org/issue26366>
_______________________________________