Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Allow .. versionadded:: next in docs #121277

Open
6 tasks done
encukou opened this issue Jul 2, 2024 · 4 comments
Open
6 tasks done

Allow .. versionadded:: next in docs #121277

encukou opened this issue Jul 2, 2024 · 4 comments
Labels
docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@encukou
Copy link
Member

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

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

Discourse announcement
@encukou encukou added the type-feature A feature request or enhancement label Jul 2, 2024
@bedevere-app bedevere-app bot mentioned this issue Jul 2, 2024
Merged
@Eclips4 Eclips4 added the docs Documentation in the Doc dir label Jul 2, 2024
@encukou
Copy link
Member Author

encukou commented Jul 2, 2024

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

@gpshead
Copy link
Member

gpshead commented 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
Copy link
Member Author

encukou commented 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 :)

@hugovk
Copy link
Member

hugovk commented 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 👍 🖌️

@encukou encukou mentioned this issue Aug 16, 2024
Merged
encukou added a commit to python/release-tools that referenced this issue Sep 24, 2024
@encukou
cpython#121277: Replace next versions in docs by the just-released …
7814f13 
…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.
encukou added a commit that referenced this issue Sep 25, 2024
@encukou @AA-Turner @hugovk
gh-121277: Allow .. versionadded:: next in docs (GH-121278)
7d24ea9 
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 <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
@encukou encukou mentioned this issue Sep 25, 2024
Merged
emilyemorehouse added a commit to lysnikolaou/cpython that referenced this issue Sep 26, 2024
@emilyemorehouse
Merge branch 'main' into fix-help-double-prompt
4cdb3ae 
* 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)
  ...
encukou added a commit to encukou/cpython that referenced this issue Sep 26, 2024
@encukou
pythongh-121277: Raise nice error on next as second argument to dep…
3cc4298 
…recated-removed
@bedevere-app bedevere-app bot mentioned this issue Sep 26, 2024
Merged
encukou added a commit that referenced this issue Sep 27, 2024
@encukou
gh-121277: Raise nice error on next as second argument to deprecate…
e349f73 
…d-removed (GH-124623)
@encukou 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
@encukou
pythongh-121277: Allow .. versionadded:: next in docs (pythonGH-121278
c339d39 
)

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 <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
(cherry picked from commit 7d24ea9)
encukou added a commit to encukou/cpython that referenced this issue Sep 27, 2024
@encukou
pythongh-121277: Raise nice error on next as second argument to dep…
99cae0e 
…recated-removed (pythonGH-124623)

(cherry-picked from e349f73)
@bedevere-app bedevere-app bot mentioned this issue Sep 27, 2024
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Documentation in the Doc dir type-feature A feature request or enhancement
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@gpshead @encukou @hugovk @Eclips4