GeezerVison is showing github.com — Allow `.. versionadded:: next` in docs · Issue #121277 · python/cpython
Allow .. versionadded:: next in docs #121277DescriptionFeature 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
Related PRs
Discourse announcement
Reacted by Nice Zombies, Gregory P. Smith and Zachary Ware Activityencukou commented on Jul 2, 2024 It might be better for the tool to live outside the cpython repo, like blurb. Reacted by Hugo van Kemenade gpshead commented on Jul 12, 2024
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 on 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 :) Reacted by Éric, Gregory P. Smith, Pradyun Gedam and Adam Turner hugovk commented on Jul 24, 2024
@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 👍 🖌️ added 2 commits that reference this issue on Sep 26, 2024gh-121277: Raise nice error on `next` as second argument to deprecate… hugovk commented on Oct 28, 2024 It worked well for 3.14.0a1, you can see the next -> 3.14 changes in 8cdaca8 👍 encukou commented on Oct 28, 2024 Reacted by Hugo van Kemenade AA-Turner commented on Jan 11, 2025 encukou commented on Jan 13, 2025 Łukasz's decision on backporting to 3.9, and then updating the devguide. encukou commented on Jan 27, 2025 Devguide PR open: python/devguide#1503
With that, I'll close this issue. Thank you everyone for feedback & reviews! Reacted by Adam Turner and Hugo van Kemenade
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|