Allow `.. versionadded:: next` in docs #121277

encukou · 2024-07-02T17:08:37Z

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

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

The text was updated successfully, but these errors were encountered:

encukou · 2024-07-02T19:37:16Z

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

gpshead · 2024-07-12T23:35:08Z

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 · 2024-07-22T09:00:27Z

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 · 2024-07-24T18:30:11Z

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

…version See: python/cpython#121277 This PR gives the RM a tool to replace all such occurences of `next` by the currently released version, baking it directly into the ReST source files, as part of the version bump commit. This is done textually (I don't know of a round-trip parser for ReST). To make sure the text manipulation worked, the released docs artifact (if it's being published) is grepped for the string `(unreleased)`, and if it's found, the RM is asked for confirmation.

Make `versionchanged:: next`` expand to current (unreleased) version. When a new CPython release is cut, the release manager will replace all such occurences of "next" with the just-released version. (See the issue for release-tools and devguide PRs.) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

* main: (69 commits) Add "annotate" SET_FUNCTION_ATTRIBUTE bit to dis. (python#124566) pythongh-124412: Add helpers for converting annotations to source format (python#124551) pythongh-119180: Disallow instantiation of ConstEvaluator objects (python#124561) For-else deserves its own section in the tutorial (python#123946) Add 3.13 as a version option to the crash issue template (python#124560) pythongh-123242: Note that type.__annotations__ may not exist (python#124557) pythongh-119180: Make FORWARDREF format look at __annotations__ first (python#124479) pythonGH-58058: Add quick reference for `ArgumentParser` to argparse docs (pythongh-124227) pythongh-41431: Add `datetime.time.strptime()` and `datetime.date.strptime()` (python#120752) pythongh-102450: Add ISO-8601 alternative for midnight to `fromisoformat()` calls. (python#105856) pythongh-124370: Add "howto" for free-threaded Python (python#124371) pythongh-121277: Allow `.. versionadded:: next` in docs (pythonGH-121278) pythongh-119400: make_ssl_certs: update reference test data automatically, pass in expiration dates as parameters python#119400 (pythonGH-119401) pythongh-119180: Avoid going through AST and eval() when possible in annotationlib (python#124337) pythongh-124448: Update Windows builds to use Tcl/Tk 8.6.15 (pythonGH-124449) pythongh-123884 Tee of tee was not producing n independent iterators (pythongh-124490) pythongh-124378: Update test_ttk for Tcl/Tk 8.6.15 (pythonGH-124542) pythongh-124513: Check args in framelocalsproxy_new() (python#124515) pythongh-101100: Add a table of class attributes to the "Custom classes" section of the data model docs (python#124480) Doc: Use ``major.minor`` for documentation distribution archive filenames (python#124489) ...

…recated-removed

…d-removed (GH-124623)

) Make `versionchanged:: next`` expand to current (unreleased) version. When a new CPython release is cut, the release manager will replace all such occurences of "next" with the just-released version. (See the issue for release-tools and devguide PRs.) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 7d24ea9)

…recated-removed (pythonGH-124623) (cherry-picked from e349f73)

…124718) * gh-121277: Allow `.. versionadded:: next` in docs (GH-121278) Make `versionchanged:: next`` expand to current (unreleased) version. When a new CPython release is cut, the release manager will replace all such occurences of "next" with the just-released version. (See the issue for release-tools and devguide PRs.) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 7d24ea9) * gh-121277: Raise nice error on `next` as second argument to deprecated-removed (GH-124623) (cherry-picked from e349f73)

…nGH-121278) (pythonGH-124718) * pythongh-121277: Allow `.. versionadded:: next` in docs (pythonGH-121278) Make `versionchanged:: next`` expand to current (unreleased) version. When a new CPython release is cut, the release manager will replace all such occurences of "next" with the just-released version. (See the issue for release-tools and devguide PRs.) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 7d24ea9) * pythongh-121277: Raise nice error on `next` as second argument to deprecated-removed (pythonGH-124623) (cherry-picked from e349f73) (cherry picked from commit dba992b) Co-authored-by: Petr Viktorin <encukou@gmail.com>

…H-125980) Make `versionchanged:: next`` expand to current (unreleased) version. When a new CPython release is cut, the release manager will replace all such occurences of "next" with the just-released version. (See the issue for release-tools and devguide PRs.) (cherry picked from commit 7d24ea9) Also backports a minor fix-up: gh-121277: Raise nice error on `next` as second argument to deprecated-removed (GH-124623) (cherry-picked from commit e349f73) Co-authored-by: Petr Viktorin <encukou@gmail.com>

encukou · 2024-10-28T13:35:27Z

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 · 2024-10-28T13:53:13Z

It worked well for 3.14.0a1, you can see the next -> 3.14 changes in 8cdaca8 👍

encukou · 2024-10-28T13:59:38Z

Yup!
Pre-releases and dot-0's do have slightly different behaviour though.

…nGH-121278) (python#124718) Make `versionchanged:: next`` expand to current (unreleased) version. When a new CPython release is cut, the release manager will replace all such occurences of "next" with the just-released version. (See the issue for release-tools and devguide PRs.) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 7d24ea9) pythongh-121277: Raise nice error on `next` as second argument to deprecated-removed (pythonGH-124623) (cherry-picked from e349f73)

…124718) (#127827) * [3.11] gh-121277: Allow `.. versionadded:: next` in docs (GH-121278) (#124718) Make `versionchanged:: next`` expand to current (unreleased) version. When a new CPython release is cut, the release manager will replace all such occurences of "next" with the just-released version. (See the issue for release-tools and devguide PRs.) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 7d24ea9) gh-121277: Raise nice error on `next` as second argument to deprecated-removed (GH-124623) (cherry-picked from e349f73) * Import VersionChange sphinx.domains.changeset.VersionChange exists at least since Sphinx 2.1, according to: https://www.sphinx-doc.org/en/master/extdev/deprecated.html * Get config from env * Use version, not arguments directly

…H-121278) Make `versionchanged:: next`` expand to current (unreleased) version. When a new CPython release is cut, the release manager will replace all such occurences of "next" with the just-released version. (See the issue for release-tools and devguide PRs.) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 7d24ea9) pythongh-121277: Raise nice error on `next` as second argument to deprecated-removed (pythonGH-124623) (cherry-picked from e349f73) Updates for 3.10 (cherry-picked from 3.11: f0895aa) * Use version, not arguments directly

…127867) Make `versionchanged:: next`` expand to current (unreleased) version. When a new CPython release is cut, the release manager will replace all such occurences of "next" with the just-released version. (See the issue for release-tools and devguide PRs.) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 7d24ea9) gh-121277: Raise nice error on `next` as second argument to deprecated-removed (GH-124623) (cherry-picked from e349f73) Updates for 3.10 (cherry-picked from 3.11: f0895aa) * Use version, not arguments directly

…-121278) (pythonGH-127867) Make `versionchanged:: next`` expand to current (unreleased) version. When a new CPython release is cut, the release manager will replace all such occurences of "next" with the just-released version. (See the issue for release-tools and devguide PRs.) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> (cherry picked from commit 7d24ea9) pythongh-121277: Raise nice error on `next` as second argument to deprecated-removed (pythonGH-124623) (cherry-picked from e349f73) Updates for 3.9 (cherry-picked from 3.11: f0895aa) (cherry-picked from 3.10: 8773554) * Use version, not arguments directly

encukou added the type-feature A feature request or enhancement label Jul 2, 2024

bedevere-app bot mentioned this issue Jul 2, 2024

gh-121277: Allow .. versionadded:: next in docs #121278

Merged

Eclips4 added the docs Documentation in the Doc dir label Jul 2, 2024

encukou mentioned this issue Aug 16, 2024

cpython#121277: Replace next versions in docs by the just-released version python/release-tools#164

Merged

encukou mentioned this issue Sep 25, 2024

Document next in versionadded & similar directives python/devguide#1413

Merged

encukou added a commit to encukou/cpython that referenced this issue Sep 26, 2024

pythongh-121277: Raise nice error on next as second argument to dep…

3cc4298

…recated-removed

bedevere-app bot mentioned this issue Sep 26, 2024

gh-121277: Raise nice error on next as second argument to deprecated-removed #124623

Merged

encukou added a commit that referenced this issue Sep 27, 2024

gh-121277: Raise nice error on next as second argument to deprecate…

e349f73

…d-removed (GH-124623)

encukou added needs backport to 3.13 bugs and security fixes and removed needs backport to 3.13 bugs and security fixes labels Sep 27, 2024

encukou added a commit to encukou/cpython that referenced this issue Sep 27, 2024

pythongh-121277: Raise nice error on next as second argument to dep…

99cae0e

…recated-removed (pythonGH-124623) (cherry-picked from e349f73)

bedevere-app bot mentioned this issue Sep 27, 2024

[3.13] gh-121277: Allow .. versionadded:: next in docs (GH-121278) #124718

Merged

miss-islington mentioned this issue Oct 25, 2024

[3.12] [3.13] gh-121277: Allow .. versionadded:: next in docs (GH-121278) (GH-124718) #125980

Merged

bedevere-app bot mentioned this issue Dec 11, 2024

[3.11] gh-121277: Allow .. versionadded:: next in docs (GH-121278) (#124718) #127827

Merged

encukou mentioned this issue Dec 12, 2024

[3.10] gh-121277: Allow .. versionadded:: next in docs (GH-121278) #127867

Merged

encukou mentioned this issue Dec 20, 2024

[3.9] gh-121277: Allow .. versionadded:: next in docs (GH-121278) #128117

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow `.. versionadded:: next` in docs #121277

Allow `.. versionadded:: next` in docs #121277

encukou commented Jul 2, 2024 •

edited by bedevere-app bot

Loading

encukou commented Jul 2, 2024

gpshead commented Jul 12, 2024

encukou commented Jul 22, 2024

hugovk commented Jul 24, 2024

encukou commented Oct 28, 2024

hugovk commented Oct 28, 2024

encukou commented Oct 28, 2024

Allow .. versionadded:: next in docs #121277

Allow .. versionadded:: next in docs #121277

Comments

encukou commented Jul 2, 2024 • edited by bedevere-app bot Loading

Feature or enhancement

Proposal:

Has this already been discussed elsewhere?

Links to previous discussion of this feature:

Linked PRs

Related PRs

Discourse announcement

encukou commented Jul 2, 2024

gpshead commented Jul 12, 2024

encukou commented Jul 22, 2024

hugovk commented Jul 24, 2024

encukou commented Oct 28, 2024

hugovk commented Oct 28, 2024

encukou commented Oct 28, 2024

Allow `.. versionadded:: next` in docs #121277

Allow `.. versionadded:: next` in docs #121277

encukou commented Jul 2, 2024 •

edited by bedevere-app bot

Loading