A frequent occurrence on CPython PRs is that a change is proposed and it includes full documentation. Time files, or PRs show up at the wrong time during a release cycle, inevitably this leads to us or the author having to manually go through the PR and update all of the .. versionadded::, .. versionchanged::, or .. versionremoved:: tags everywhere in the .rst files edited within the PR to be the version we predict it will be merged in time for (we’re not always correct on some things, turning this process into a slow loop).
This is manual work that doesn’t need to be. There are multiple ways forward with this:
A) Can we teach our ReST docs compiler about a special version value such as “next” which it would then render as the correct value in the output docs? (do we even care if it renders as the correct value?)
This would add a one time Release Manager process to, just before release branch creation while the repo is locked, run a program that converts all of these Docs “next” tags in place to be the X.Y version string and commit that.
OR
B) A CI check that blocks merging if main hasn’t been merged into the PR since the last X.Y major release combined with a CI task dependent on that which edits the PR in place (requiring a triager level button click to merge its proposed change would be fine).
… probably other ways as well …
Inspiration for this idea comes from our Misc/NEWS solution to this problem of everything happily living conflict free in a Misc/NEWS.d/next/ subdirectory which gets officially versionified as part of the release branching process. That’s been working well, so lets do more of that?
do we even care if it renders as the correct value?
No. Well, yes: we should put some thought into choosing the correct value, as “next” might be too opaque for users. AFAIK, the de-facto standard term in changelogs is “unreleased”.
Then again, the target audience is people building docs from source. They can cope.
This would add a one time Release Manager process to, just before release branch creation while the repo is locked, run a program that converts all of these Docs “next” tags in place to be the X.Y version string and commit that.
I don’t think there’s API for style-preserving modifications to ReST, so this would probably be a regex search-and-replace, followed by a special build that checks if any occurrences were forgotten.
Full disclosure: For work, I backport patches to old versions of Python. Too often I to dismiss nitpicky reviews with “we don’t build those docs anyway”.
This should be easy enough though, as they’ll all be on lines starting with .. version(changed|added), and currently should never say next.
I believe there’s a way to define a ReST variable, probably something .. versionadded: ..next or next_, but I doubt that’s worth fighting with.
The bigger challenge will be the argument over whether to specify the prerelease in the docs, or round up to the .0 release. It would be great to show specific prerelease versions during prereleases, but that pushes us right into complex territory.
I also wouldn’t be totally against having one source of docs for all versions and just list everything in versionchanged. But that probably requires us to not make so many breaking changes
