FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Document ``next`` in versionadded & similar directives by encukou · Pull Request #1413 · python/devguide · GitHub

Document next in versionadded & similar directives - #1413

Merged
encukou merged 1 commit into
python:mainfrom
encukou:versionadded-next
Sep 27, 2024
Merged

Document next in versionadded & similar directives#1413
encukou merged 1 commit into
python:mainfrom
encukou:versionadded-next

Conversation

encukou commented Sep 25, 2024
edited
Loading

Copy link
Copy Markdown
Member

Comment thread documentation/markup.rst
Comment on lines +1115 to +1117
When backporting to versions before 3.14, check if ``Doc/tools/extensions/pyspecific.py``
contains the function ``expand_version_arg``. If it's not there,
use a specific version instead of ``next``.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

It would be better to just decide which versions next should be backported to, backport it, and then list those versions here.

Can you also clarify when would backporting be necessary for a versionadded? New features should be documented on the next release, and not backported to previous versions.

The only exception I can think of is if we are documenting an addition after the fact, but this is covered in the next paragraph.

versionchanged are more likely to be backported, so maybe this paragraph should be moved there.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Maybe, but practically, sometimes the backporting decisions take weeks; I don't think they shouldn't block the PR to main.

New API is sometimes added for security fixes, either to enable old behaviour in cases where it's so insecure that we change the default, or to enable new secure behaviour. (Also: third-party redistributors can backport features. That's not what the devguide documents, but the tooling is built with that in mind.)

versionchanged sharts with “Similar to versionadded”, so I added the docs here.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

To clarify, with the first sentence I meant the support for next itself. IOW, if next is supported from e.g. 3.12+, then the docs should simply say something like "When backporting to versions before 3.12, use a specific version instead of next.". If you are planning to use the current wording until the support for next has been backported and then update this paragraph accordingly, that's ok (assuming that next does the right thing when used on older versions).

For security fixes and similar I was thinking that are more likely to be versionchanged, but sometimes new APIs are indeed added. Since the docs for versionchanged start with "Similar to versionadded", I now think it's ok to leave the paragraph here.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Oh! Yes, I expect to change the wording after backporting the feature, and I plan to talk to RMs after this is merged and announced.

Comment thread documentation/markup.rst
Comment thread documentation/markup.rst
There are two required arguments: the version from which the feature is
deprecated, and the version in which the feature is removed.
deprecated (usually ``next``), and the version in which the feature
is removed, which must be a specific version number (*not* ``next``).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Does the tool that convert next check this?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Not explicitly, but it will fail.
For a check with a nice error message, could you review python/cpython#124623?

It's not a big priority, since next doesn't really make sense here.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Thanks for fixing that!
I left a review.

encukou merged commit f7b933c into python:main Sep 27, 2024
encukou deleted the versionadded-next branch October 1, 2024 14:11
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants


Back | FazBrowse Home | New Git URL