Document next in versionadded & similar directives
#1413
Conversation
| 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``. |
There was a problem hiding this comment.
It would be better to just decide which versions next should be backported to, backport it, and then list those versions here.
Can you also clarify when would backporting be necessary for a versionadded? New features should be documented on the next release, and not backported to previous versions.
The only exception I can think of is if we are documenting an addition after the fact, but this is covered in the next paragraph.
versionchanged are more likely to be backported, so maybe this paragraph should be moved there.
There was a problem hiding this comment.
Maybe, but practically, sometimes the backporting decisions take weeks; I don't think they shouldn't block the PR to main.
New API is sometimes added for security fixes, either to enable old behaviour in cases where it's so insecure that we change the default, or to enable new secure behaviour. (Also: third-party redistributors can backport features. That's not what the devguide documents, but the tooling is built with that in mind.)
versionchanged sharts with “Similar to versionadded”, so I added the docs here.
There was a problem hiding this comment.
To clarify, with the first sentence I meant the support for next itself. IOW, if next is supported from e.g. 3.12+, then the docs should simply say something like "When backporting to versions before 3.12, use a specific version instead of next.". If you are planning to use the current wording until the support for next has been backported and then update this paragraph accordingly, that's ok (assuming that next does the right thing when used on older versions).
For security fixes and similar I was thinking that are more likely to be versionchanged, but sometimes new APIs are indeed added. Since the docs for versionchanged start with "Similar to versionadded", I now think it's ok to leave the paragraph here.
There was a problem hiding this comment.
Oh! Yes, I expect to change the wording after backporting the feature, and I plan to talk to RMs after this is merged and announced.
|
|
||
| .. 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``). |
There was a problem hiding this comment.
Does the tool that convert next check this?
There was a problem hiding this comment.
Not explicitly, but it will fail.
For a check with a nice error message, could you review python/cpython#124623?
It's not a big priority, since next doesn't really make sense here.
There was a problem hiding this comment.
Thanks for fixing that!
I left a review.
See python/cpython#121277
📚 Documentation preview 📚: https://cpython-devguide--1413.org.readthedocs.build/