I don’t know whether this has already been discussed (quite hard for me to guess what kind of topic I should search for actually) but I would like to know whether it is possible to mark a feature that was just added as being available for the “next” release since the docs are actually not synchronized with the actual patch.
More precisely, after introducing some new features to symtable that will be available in 3.13.0b3 and 3.14, I wanted to update the corresponding stubs on typeshed. The online docs at that time, namely those that are accessible, mentioned “3.13” and " Welcome! This is the official documentation for Python 3.13.0b2". However, those features would have only been present in 3.13.0b3 since the implementation was done after the b2 release.
I would like to know whether you would be willing to develop a Sphinx extension or a pre-commit task which would do the following:
If a feature is added explicitly using .. versionadded:: 3.13 and if the current build is 3.13.0b2 for instance, then a small note would say “this feature will be available in the next patch” or something like that. That way, you wouldn’t assume that the current release contains the feature.
Alternatively, people adding features would instead use another directive, say nextversionadded:: 3.13 which, after the release, would transform into versionadded. Or you can tweak the versionadded directive to support an additional option :next:.
I didn’t want to create an issue since I feel that this needs a bit more of a discussion. In addition, I did not think yet of corner cases nor whether this would really be helpful for users in general. At least, it would have been helpful to me in order to remember what is actually fine and what is actually scheduled in the next patch.
Ah ! thank you Petr, I didn’t know about that topic (as I said I didn’t know what to search in the first place). Should I close the discussion or should I keep it open to submit implementation ideas? Unfortunately, the Sphinx implementation of .. versionadded:: currently disallows options. And if I were to make it happen, it could break the directive, so it could only be done in Sphinx 9.0 or if we add a new directive (which I don’t want to). IMO CPython could have its own versionadded directive, or some pre-commit tool for that (see below for examples).
I don’t have a good suggestion for the other discussion issue but I can try to think of a nice and easy way to mark a feature as being the next to be released.
Example
PR is written when the current release is 3.15.0a1.
PR contains:
.. versionadded:: 3.15
pre-commit just before the merge: current release == 3.15.0a1, so we transform .. versionadded:: 3.15 into .. nextversionadded:: 3.15 (this should be automatic with some search-and-replace).
PR is merged. The feature will be available in 3.15.0a2.
Rebuild docs (I think they are built nightly). The directive .. nextversionadded:: 3.15 would look exactly like a .. versionadded::, but it would have some additional text saying “this feature will be available in 3.15.0a2”. Note that you’ll need some constant in conf.py telling you the next release version but I think this can also be bumped automatically whenever you release something (or this can be done manually by the release manager).
Whenever docs are rebuilt, we have .. nextversionadded:: 3.15 and we wouldn’t worry about. If another PR needs to amend that, since it’s anyway now hardcoded, we can easily change it in case of an issue.
When 3.15.0a2 is released, docs are compiled with .. nextversionadded:: 3.15 and since it is the same major version, then some search-and-replace would change it to .. versionadded:: 3.15 (the normal one). Online docs will not have the warning anymore.
A similar logic should be done for .. versionchanged::. Note that at any time, there will be no released version of Python with a .. nextversionadded:: directive inside it since those will always be consumed just before the release.
Do you think this kind of implementation make sense for this specific issue? I don’t think we should have an automatic way for updating a PR that was written, say, in 3.12 and that has something saying .. versionadded:: 3.13. For those kind of PRs, I would advise to explicitly replace the version. Otherwise, you could have .. futureversionadded:: [TEXT] with an optional text and which would automatically assume that the +1 release would be added when your PR is merged. For instance:
PR is written in 3.15.
PR contains:
.. futureversionadded:: support brackets :)
PR is stalled for a long time.
PR is accepted and would be added in 3.33.0a1.
When PR is merged, .. futureversionadded:: is transformed into .. nextversionadded: 3.33. The rest is as in the previous example.
AFAIK, it does not make sense to have .. nextversionadded: X.Y with X.Y different from the current major/minor Python versions (neither for the “changed” and “removed” counterparts).
I’ve opened an issue with a proposed implementation: Issue: #121277
It’ll probably be best to keep the discussion there or on the earlier thread.
The nextversionadded idea sounds good. If a Sphinx expert tells me that subclassing VersionChange and reassigning self.arguments is a bad idea, I’ll try that
Well, it’s mainly because we don’t make the difference between:
.. versionadded:: version
text
other text
and
.. versionadded:: version
maybe_options
other text
IIRC, the maybe_options is still treated as a regular text =/ (honestly, I don’t know why it was decided as such) and because of this, it means that the :next: in
.. versionadded:: version
:next:
other text
would not be treated as an option but as a regular sentence… I’ll close this specific discussion then and I’ll go comment on the issue directly (err… how can I close it?)
