Feature or enhancement

Proposal:

In a PR to CPython, theversionadded,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 anext/ directory before a release, when the release manager bundles them up and assigns a version.

Concrete proposal:

• Teachversionadded & the others to expand the version argumentnext to<version> (unreleased) (e.g.3.14.0b0 (unreleased)).
• Add a tool that replaces thenext 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 thatbuilt 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 onnext 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: Replacenext versions in docs by the just-released version release-tools#164
• devguide PR:Documentnext in versionadded & similar directives devguide#1413

Discourse announcement

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