Document next in versionadded & similar directives (GH-1413)

Author: encukou

documentation/markup.rst

@@ -1083,16 +1083,42 @@ units as well as normal text:
    (``class``, ``attribute``, ``function``, ``method``, ``c:type``, etc),
    a ``versionadded`` should be included at the end of its description block.
 
-   The first argument must be given and is the version in question.  The second
-   argument is optional and can be used to describe the details of the feature.
+   The first argument must be given and is the version in question.
+   Instead of a specific version number, you can---and should---use
+   the word ``next``, indicating that the API will first appear in the
+   upcoming release.
+   The second argument is optional and can be used to describe the details of the feature.
 
    Example::
 
       .. function:: func()
 
          Return foo and bar.
 
-         .. versionadded:: 3.5
+         .. versionadded:: next
+
+   When a release is made, the release manager will change the ``next`` to
+   the just-released version. For example, if ``func`` in the above example is
+   released in 3.14, the snippet will be changed to::
+
+      .. function:: func()
+
+         Return foo and bar.
+
+         .. versionadded:: 3.14
+
+   The tool to do this replacement is `update_version_next.py`_
+   in the release-tools repository.
+
+   .. _update_version_next.py: https://github.com/python/release-tools/blob/master/update_version_next.py
+
+   When backporting to versions before 3.14, check if ``Doc/tools/extensions/pyspecific.py``
+   contains the function ``expand_version_arg``. If it's not there,
+   use a specific version instead of ``next``.
+
+   When adding documentation for a function that existed in a past version,
+   but wasn't documented yet, use the version number where the function was
+   added instead of ``next``.
 
 .. describe:: versionchanged
 
@@ -1106,7 +1132,7 @@ units as well as normal text:
 
          Return foo and bar, optionally with *spam* applied.
 
-         .. versionchanged:: 3.6
+         .. versionchanged:: next
             Added the *spam* parameter.
 
    Note that there should be no blank line between the directive head and the
@@ -1118,22 +1144,25 @@ units as well as normal text:
 
    There is one required argument: the version from which the feature is
    deprecated.
+   Similarly to ``versionadded``, you should use the word ``next`` to indicate
+   the API will be first deprecated in the upcoming release.
 
    Example::
 
-      .. deprecated:: 3.8
+      .. deprecated:: next
 
 .. describe:: deprecated-removed
 
    Like ``deprecated``, but it also indicates in which version the feature is
    removed.
 
    There are two required arguments: the version from which the feature is
-   deprecated, and the version in which the feature is removed.
+   deprecated (usually ``next``), and the version in which the feature
+   is removed, which must be a specific version number (*not* ``next``).
 
    Example::
 
-      .. deprecated-removed:: 3.8 4.0
+      .. deprecated-removed:: next 4.0
 
 .. describe:: impl-detail