Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Add a guide to deprecating features #1469

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

Draft
Lincoln-developer wants to merge 11 commits into python:main
base: main
Choose a base branch
Loading
from Lincoln-developer:fix-issue-1419

Conversation

@Lincoln-developer
Copy link
Contributor

@Lincoln-developer Lincoln-developer commented Nov 8, 2024 •
edited by hugovk
Loading

This pull request introduces a new section in the Developer Guide to document the practical steps for deprecating features in CPython. It complements the policy guidelines outlined in PEP 387 by providing a detailed, actionable workflow for contributors

📚 Documentation preview 📚: https://cpython-devguide--1469.org.readthedocs.build/developer-workflow/cpython-deprecation-workflow/

Copy link
Member

@AA-Turner AA-Turner left a comment

Choose a reason for hiding this comment

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

I think we can make a few improvements here specific to CPython.

A

P.S. Out of idle curiosity, did you use an LLM/GPT to help write this document? There's a couple of hallmarks I recognise, but it could just be a general style!

Comment on lines 25 to 39
* **Raise a Warning**: Use :func:`warnings.warn` with :exc:`DeprecationWarning` for typical cases.
If the feature is in its early deprecation phase:

* Use :exc:`PendingDeprecationWarning` initially, which transitions to :exc:`DeprecationWarning` after a suitable period.

Example:

.. code-block:: python
import warnings
warnings.warn(
"Feature X is deprecated and will be removed in Python 3.Y",
DeprecationWarning,
stacklevel=2
)
Copy link
Member

@AA-Turner AA-Turner Nov 8, 2024

Choose a reason for hiding this comment

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

We should probably use warnings._deprecated() instead here

Copy link
Contributor Author

@Lincoln-developer Lincoln-developer Nov 8, 2024

Choose a reason for hiding this comment

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

Thanks let me work on this change

------------------------------------
Before proposing deprecation:

* **Assess Usage**: Use tools like GitHub search, ``grep``, or ``PyPI statistics`` to determine the extent and context of usage.
Copy link
Member

@AA-Turner AA-Turner Nov 8, 2024

Choose a reason for hiding this comment

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

Perhaps you could add links here?

Copy link
Contributor Author

@Lincoln-developer Lincoln-developer Nov 8, 2024

Choose a reason for hiding this comment

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

okay sure, let me add them

@AA-Turner AA-Turner changed the title (削除) gh-1419: Added deprecation workflow for CPython. (削除ここまで) (追記) Add a guide to deprecating features (追記ここまで) Nov 8, 2024
Lincoln-developer and others added 8 commits November 8, 2024 16:07 
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Copy link

python-cla-bot bot commented Apr 18, 2025 •
edited
Loading

All commit authors signed the Contributor License Agreement.

CLA signed


Once approved:

* **Raise a Warning**: Use ``warnings._deprecated`` with :exc:`DeprecationWarning` for typical cases.
Copy link
Member

@StanFromIreland StanFromIreland Sep 8, 2025

Choose a reason for hiding this comment

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

Why is this preferred over the documented and more common warnings.warn (over 3x in the stdlib)?

Comment on lines +1 to +2
Workflow for Deprecating Features in CPython
==============================================
Copy link
Member

@StanFromIreland StanFromIreland Sep 8, 2025

Choose a reason for hiding this comment

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

Suggested change
Workflow for Deprecating Features in CPython
==============================================
Workflow for Deprecating Features in CPython
============================================

Workflow for Deprecating Features in CPython
==============================================

Deprecation in CPython is a multi-step process that involves notifying users about deprecated functionality, planning its eventual removal, and providing adequate guidance for migration.
Copy link
Member

@StanFromIreland StanFromIreland Sep 8, 2025

Choose a reason for hiding this comment

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

Please wrap lines to 79 characters.


Before proposing deprecation:

* **Assess Usage**: Use tools like GitHub search, `grep`_, or `PyPI statistics`_ to determine the extent and context of usage.
Copy link
Member

@StanFromIreland StanFromIreland Sep 8, 2025

Choose a reason for hiding this comment

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

Maybe add a link to the GitHub search and list Victor's script: https://hugovk.dev/blog/2022/how-to-search-5000-python-projects/ ?

Open an issue
-------------

Start by creating a GitHub issue to propose the deprecation:
Copy link
Member

@StanFromIreland StanFromIreland Sep 8, 2025

Choose a reason for hiding this comment

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

I think we should recommend a thread on Discourse first?

------------------

* **Monitor Usage**: After the release, observe community feedback. Deprecations may remain longer than the minimum period if low maintenance overhead is expected or usage is widespread.
* **Timeline Review**: Use GitHub milestones or specific deprecation tracking issues to manage timelines.
Copy link
Member

@StanFromIreland StanFromIreland Sep 8, 2025

Choose a reason for hiding this comment

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

GitHub milestones

These are not used in CPython?

* Update documentation, removing references to the deprecated feature.
* Include the removal in the "What's New" for the release.

``PendingDeprecationWarning`` workflow
Copy link
Member

@StanFromIreland StanFromIreland Sep 8, 2025

Choose a reason for hiding this comment

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

This stage seems odd, how often is this done?

------------------------

* Use the ``.. deprecated-removed::`` roles for documentation.
* Add ``See Also`` links to :pep:`387` and DevGuide for policy and process details.
Copy link
Member

@StanFromIreland StanFromIreland Sep 8, 2025

Choose a reason for hiding this comment

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

I don't understand, do you suggest a .. see-also:: under every deprecated feature?

* No ``pending-removal-in`` entry is needed during this stage.

References and templates
------------------------
Copy link
Member

@StanFromIreland StanFromIreland Sep 8, 2025

Choose a reason for hiding this comment

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

We can also link to PEP 4

:maxdepth: 5

communication-channels
cpython-deprecation-workflow
Copy link
Member

@StanFromIreland StanFromIreland Sep 8, 2025

Choose a reason for hiding this comment

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

This should definitely be below development cycle

@StanFromIreland StanFromIreland marked this pull request as draft September 8, 2025 21:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StanFromIreland StanFromIreland StanFromIreland left review comments

@AA-Turner AA-Turner Awaiting requested review from AA-Turner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Document the workflow for deprecating something in CPython.

AltStyle によって変換されたページ (->オリジナル) /