encukou commented 4 months ago

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:

[x] Teach versionadded & the others to expand the version argument next to <version> (unreleased) (e.g. 3.14.0b0 (unreleased)).
[x] Add a tool that replaces the next with a given string (e.g. 3.14).
[x] Modify the release manager tooling to run the tool on release.
[x] 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.
[x] Update the Devguide.
[x] 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-121278
gh-124623
gh-124718
gh-125980

Related PRs

release-tools PR: https://github.com/python/release-tools/pull/164
devguide PR: https://github.com/python/devguide/pull/1413

Discourse announcement

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

encukou commented 4 months ago

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

gpshead commented 3 months ago

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 commented 3 months ago

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 commented 3 months ago

@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 👍 🖌️

encukou commented 1 week ago

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 commented 1 week ago

It worked well for 3.14.0a1, you can see the next -> 3.14 changes in https://github.com/python/cpython/commit/8cdaca8b25e3354530d66cbccc622e0e914e8e8a 👍