# Automating versionadded & changed markers in Docs to expedite PRs
**URL:** https://discuss.python.org/t/automating-versionadded-changed-markers-in-docs-to-expedite-prs/38423
**Category:** Core Development
**Tags:** documentation, workflow
**Created:** [November 11, 2023, 12:57am UTC](https://discuss.python.org/t/automating-versionadded-changed-markers-in-docs-to-expedite-prs/38423 "2023-11-11T00:57:02Z")
**Posts on this page:** 4
**Page:** 1
### Author:  [@gpshead](https://discuss.python.org/u/gpshead)
#### Post date: [November 11, 2023, 12:57am UTC](https://discuss.python.org/t/automating-versionadded-changed-markers-in-docs-to-expedite-prs/38423/1 "2023-11-11T00:57:02Z")
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?
---
### Author:  [@encukou](https://discuss.python.org/u/encukou)
#### Post date: [November 13, 2023, 9:16am UTC](https://discuss.python.org/t/automating-versionadded-changed-markers-in-docs-to-expedite-prs/38423/2 "2023-11-13T09:16:58Z")
Oooh, **A)** sounds like a great idea!
> 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”](https://keepachangelog.com/en/1.1.0/#effort).
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”._
---
### Author:  [@steve.dower](https://discuss.python.org/u/steve.dower)
#### Post date: [November 13, 2023, 7:51pm UTC](https://discuss.python.org/t/automating-versionadded-changed-markers-in-docs-to-expedite-prs/38423/3 "2023-11-13T19:51:45Z")
> [@encukou](#):
>
> I don’t think there’s API for style-preserving modifications to ReST, so this would probably be a regex search-and-replace
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 😃
---
### Author:  [@encukou](https://discuss.python.org/u/encukou)
#### Post date: [July 2, 2024, 5:12pm UTC](https://discuss.python.org/t/automating-versionadded-changed-markers-in-docs-to-expedite-prs/38423/4 "2024-07-02T17:12:51Z")
A concrete proposal:
- Teach `versionadded` & the others to expand the version argument `next` to ` (unreleased)` (e.g. `3.14.0b0 (unreleased)`).
- Add a tool for release managers to replaces the `next` with a given string (e.g. `3.14`).
Issue: [#121277](https://github.com/python/cpython/issues/121277)
Draft implementation in cpython: [#121278](https://github.com/python/cpython/pull/121278/files)