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 inPEP 387 by providing a detailed, actionable workflow for contributors

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

Lincoln-developer added2 commits

November 8, 2024 15:24

Added deprecation workflow in CPython.

f2fd360

Fixed sphinx-linting error

e99387d

AA-Turner requested changes

Nov 8, 2024

View reviewed changes

Copy link

Member

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.

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!

developer-workflow/cpython-deprecation-workflow.rst Outdated

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-TurnerNov 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 usewarnings._deprecated() instead here

Copy link

ContributorAuthor

Lincoln-developerNov 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

developer-workflow/cpython-deprecation-workflow.rst OutdatedShow resolvedHide resolved

developer-workflow/cpython-deprecation-workflow.rst Outdated

		------------------------------------
		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-TurnerNov 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

ContributorAuthor

Lincoln-developerNov 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

developer-workflow/cpython-deprecation-workflow.rst OutdatedShow resolvedHide resolved

AA-Turner changed the title~~gh-1419: Added deprecation workflow for CPython.~~Add a guide to deprecating features

Nov 8, 2024

AA-Turner linked an issue

Nov 8, 2024

that may beclosed by this pull request

Document the workflow for deprecating something in CPython.#1419

Open

Lincoln-developerand others added8 commits

November 8, 2024 16:07