Repository navigation
Allow .. versionadded:: next in docs #121277
Description
Feature or enhancement
Proposal:
In a PR to CPython, the versionadded, versionchanged, versionremoved, deprecated, deprecated-removed directives in documentation should currently be set to the upcoming release.
This is inconvenient:
- the numbers need to be changed in backports
- if a PR misses a feature release, the number needs to be updated
It would be good to treat this more like News entries, which live in a next/ directory before a release, when the release manager bundles them up and assigns a version.
Concrete proposal:
- Teach
versionadded& the others to expand the version argumentnextto<version> (unreleased)(e.g.3.14.0b0 (unreleased)). - Add a tool that replaces the
nextwith a given string (e.g.3.14). - Modify the release manager tooling to run the tool on release.
- Add a check to release manager tooling that built HTML documentation for a fresh release does not include the string
(unreleased). The RM should be able to skip this test, in case of a false positive. - Update the Devguide.
- Announce in Discourse
Has this already been discussed elsewhere?
I have already discussed this feature proposal on Discourse
Links to previous discussion of this feature:
https://discuss.python.org/t/automating-versionadded-changed-markers-in-docs-to-expedite-prs/38423
Linked PRs
- gh-121277: Allow
.. versionadded:: nextin docs #121278 - gh-121277: Raise nice error on
nextas second argument to deprecated-removed #124623 - [3.13] gh-121277: Allow
.. versionadded:: nextin docs (GH-121278) #124718 - [3.12] [3.13] gh-121277: Allow
.. versionadded:: nextin docs (GH-121278) (GH-124718) #125980 - [3.11] gh-121277: Allow .. versionadded:: next in docs (GH-121278) (#124718) #127827
- [3.10] gh-121277: Allow .. versionadded:: next in docs (GH-121278) #127867
- [3.9] gh-121277: Allow .. versionadded:: next in docs (GH-121278) #128117
Related PRs
- release-tools PR: cpython#121277: Replace
nextversions in docs by the just-released version release-tools#164 - devguide PR: Document
nextin versionadded & similar directives devguide#1413
Activity
encukou commentedon Jul 2, 2024
It might be better for the tool to live outside the cpython repo, like blurb.
gpshead commentedon Jul 12, 2024
The tool for replacing version "next" in .rst files with the number makes sense to keep in repo to me (as your draft PR does for now) as it is small. Really not a lot more than could be done with some inscrutable
sedcommands.encukou commentedon Jul 22, 2024
It's small, but there can still be bugs in it, and it'd be easier to deal with those if we don't need to backport them.
@hugovk You said elsewhere that you'd prefer the version-bumping tool to live outside CPython repo. Since it's so small, I'd add it (and its test) to https://github.com/python/release-tools directly. Would that work?
You're a RM, so you get to choose the bikeshed paint here :)
hugovk commentedon Jul 24, 2024
Yep, this sounds good 👍 🖌️
cpython#121277: Replace `next` versions in docs by the just-released …
gh-121277: Allow `.. versionadded:: next` in docs (GH-121278)
Merge branch 'main' into fix-help-double-prompt
pythongh-121277: Raise nice error on `next` as second argument to dep…
gh-121277: Raise nice error on `next` as second argument to deprecate…
pythongh-121277: Allow `.. versionadded:: next` in docs (pythonGH-121278
pythongh-121277: Raise nice error on `next` as second argument to dep…
3 remaining items
encukou commentedon Oct 28, 2024
It's now in 3.13 & 3.12. I plan to wait for releases from those branches before offering this to RMs of the security-only ones. (This is obviously not a security fix, but as a feature designed to make backporting easier, it might get an exception.)
hugovk commentedon Oct 28, 2024
It worked well for 3.14.0a1, you can see the
next->3.14changes in 8cdaca8 👍encukou commentedon Oct 28, 2024
Yup!
Pre-releases and dot-0's do have slightly different behaviour though.
[3.11] pythongh-121277: Allow `.. versionadded:: next` in docs (pytho…
[3.11] gh-121277: Allow .. versionadded:: next in docs (GH-121278) (#…
[3.10] pythongh-121277: Allow .. versionadded:: next in docs (pythonG…
[3.10] pythongh-121277: Allow .. versionadded:: next in docs (pythonG…
[3.10] gh-121277: Allow .. versionadded:: next in docs (GH-121278) (#…
[3.9] pythongh-121277: Allow .. versionadded:: next in docs (pythonGH…
AA-Turner commentedon Jan 11, 2025
@encukou anything left here?
A
encukou commentedon Jan 13, 2025
Łukasz's decision on backporting to 3.9, and then updating the devguide.
[3.9] gh-121277: Allow .. versionadded:: next in docs (GH-121278) (#1…
encukou commentedon Jan 27, 2025
Devguide PR open: python/devguide#1503
With that, I'll close this issue. Thank you everyone for feedback & reviews!
cpython#121277: Replace `next` versions in docs by the just-released …