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