Allow `.. versionadded:: next` in docs

[encukou]

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 argument next to <version> (unreleased) (e.g. 3.14.0b0 (unreleased)).
• Add a tool that replaces the next with 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:: next in docs #121278
• gh-121277: Raise nice error on next as second argument to deprecated-removed #124623
• [3.13] gh-121277: Allow .. versionadded:: next in docs (GH-121278) #124718
• [3.12] [3.13] gh-121277: Allow .. versionadded:: next in 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 next versions in docs by the just-released version release-tools#164
• devguide PR: Document next in versionadded & similar directives devguide#1413

Discourse announcement

• https://discuss.python.org/t/versionadded-next/65280

[encukou]

It might be better for the tool to live outside the cpython repo, like blurb.

[gpshead]

It might be better for the tool to live outside the cpython repo, like blurb.

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 sed commands.

[encukou]

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]

@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 python/release-tools directly. Would that work?

Yep, this sounds good 👍 🖌️