8000 gh-115664: Reorganize versionadded directives for -X options by serhiy-storchaka · Pull Request #116304 · python/cpython · GitHub
[go: up one dir, main page]

Skip to content

gh-115664: Reorganize versionadded directives for -X options #116304

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.

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

Merged

Conversation

serhiy-storchaka
Copy link
Member
@serhiy-storchaka serhiy-storchaka commented Mar 4, 2024

Add the versionadded directives just under the description of the corresponding option.

It is an alternative to changes in #116298.


📚 Documentation preview 📚: https://cpython-previews--116304.org.readthedocs.build/

Add the versionadded directives just under the description of the
corresponding option.
Comment on lines 539 to 544
.. versionchanged:: 3.8
The :class:`io.IOBase` destructor logs ``close()`` exceptions.

.. versionchanged:: 3.9
Check the *encoding* and *errors* arguments for string encoding
and decoding operations.
Copy link
Member Author

Choose a reason for hiding this comment

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

I am not sure about these two. The Python Development Mode is now described in details in Doc/library/devmode.rst, where there are corresponding versionchanged directives. So perhaps there is no need to duplicate them here. Perhaps they are remnants from the time when it all was described here.

Comment on lines 538 to 544

.. versionchanged:: 3.8
The :class:`io.IOBase` destructor logs ``close()`` exceptions.

.. versionchanged:: 3.9
Check the *encoding* and *errors* arguments for string encoding
and decoding operations.
Copy link
Member Author

Choose a reason for hiding this comment

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

Suggested change
.. versionchanged:: 3.8
The :class:`io.IOBase` destructor logs ``close()`` exceptions.
.. versionchanged:: 3.9
Check the *encoding* and *errors* arguments for string encoding
and decoding operations.

@hugovk hugovk removed the needs backport to 3.11 only security fixes label Apr 11, 2024
Copy link
Member
@hugovk hugovk left a comment

Choose a reason for hiding this comment

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

Thanks, this is an improvement. A couple of questions about keeping info about removals.

Comment on lines 584 to 594
.. versionchanged:: 3.9
Using ``-X dev`` option, check *encoding* and *errors* arguments on
string encoding and decoding operations.

The ``-X showalloccount`` option has been removed.
Copy link
Member

Choose a reason for hiding this comment

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

I think it's still useful to know -X showalloccount was removed in 3.9?

For example, if I'm migrating from 3.8 to 3.9, I might want to know this option has gone.

Copy link
Member Author

Choose a reason for hiding this comment

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

Done. Although it is slightly inconsistent. Either we document an entity (class, method) separately, with versionadded, and when remove it, nothing is left. Or we document it (function parameters) in the documentation of other entity, with versionc 8000 hanged for the enclosing entity, and after removing them, we can add a new versionchanged. There is no strong division by types. Attributes can be documented in both ways, and sometimes methods and even classes are not documented as separate entities.

Comment on lines 590 to 598
.. versionchanged:: 3.10
Added the ``-X warn_default_encoding`` option.
Removed the ``-X oldparser`` option.
Copy link
Member

Choose a reason for hiding this comment

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

Similarly about -X oldparser being removed in 3.10.

Copy link
Member
@hugovk hugovk left a comment

Choose a reason for hiding this comment

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

Thanks!

@miss-islington-app
Copy link

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

@serhiy-storchaka serhiy-storchaka deleted the docs-versionadded-xoptions branch April 15, 2024 15:01
@miss-islington-app
Copy link

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 10f1a2687a080f07bc128e185c854586207f08cf 3.12

@serhiy-storchaka
Copy link
Member Author

Thank you for your review @hugovk.

serhiy-storchaka added a commit to serhiy-storchaka/cpython that referenced this pull request Apr 15, 2024
…ions (pythonGH-116304)

Add the versionadded directives just under the description of the
corresponding option.
(cherry picked from commit 10f1a26)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
@bedevere-app
Copy link
bedevere-app bot commented Apr 15, 2024

GH-117900 is a backport of this pull request to the 3.12 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.12 only security fixes label Apr 15, 2024
serhiy-storchaka added a commit that referenced this pull request Apr 15, 2024
…H-116304) (GH-117900)

Add the versionadded directives just under the description of the
corresponding option.
(cherry picked from commit 10f1a26)
diegorusso pushed a commit to diegorusso/cpython that referenced this pull request Apr 17, 2024
…ythonGH-116304)

Add the versionadded directives just under the description of the
corresponding option.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants
0