Document the workflow for deprecating something in CPython.

[Mariatta]

Describe the enhancement or feature you'd like
Document the workflow on how to deprecate something in CPython.
Deprecating something in Python involves raising deprecation warning and then actually removing the code some time later (at least 2 release cycles). We don't have this process documented clearly.

Describe alternatives you've considered
Currently this is undocumented process, and each of us has to just figure it out somehow.

Additional context
Discussed on Discord core-workflow-and-bots channel, and now opening a ticket based on the discussions.

Basic process:

• An issue was opened calling for deprecation of something
• We deprecate the code by adding warnings.deprecated (or warnings._deprecated)
• Document the deprecation. Needs a Porting doc (how?)
• The issue can be closed after the code for adding deprecation has been merged. It doesn't need to stay open for 2+ more years.
• Add the deprecation to the pending-removal-in....rst file
• At the scheduled removal year, open a new issue for the removal
• Finally remove the code

Other info:

• Some deprecations don't have set removal date.
• There are also deprecated-removed Sphinx role to help advertise the removal dates.
• How to decide whether Removal/Deprecation is the right solution?
  • search the usage, search on GitHub, grep, check PyPI projects to get an idea of the widespread usage
  • when searching, look not just if people are using it, but how they're using it. Document the use case for the porting notes
• Is there a template for deprecation warning message?
• Should have documentation about how to port/replace it (porting notes)
• Users are encouraged to give feedback about deprecation by filing an issue

Note there is an open proposal for extending the removal of deprecated code to 5 years instead of 2.

[encukou]

This process is documented in PEP-387's Making Incompatible Changes section.
It mentions the 2-release minimum, but also:

• If the expected maintenance overhead and security risk of the deprecated behavior is small (e.g. an old function is reimplemented in terms of a new, more general one), it can stay indefinitely (or until the situation changes).
• If the deprecated feature is replaced by a new one, it should generally be removed only after the last Python version without the new feature reaches end of support.

Also there's a "See if there’s any feedback" step, discussion, typeshed, and a mention of Py_DEPRECATED for C API deprecations.

[hugovk]

PEP 387 is the policy, and indeed includes the minimum and recommendations about a longer deprecation period.

However, I think it would be useful to have a practical guide in the devguide about the concrete steps (usually) needed, which don't belong in the PEP.

The devguide instructions should of course refer to the PEP for the policy details.

[Mariatta]

Hmm, I was expecting to find this info on the devguide, under Development Workflow.
I think some docs in the peps repo really should be more in the devguide instead of the PEP, or perhaps the PEP can be the proposal, the background story.

The PEP also doesn't say stuff like: go add this to the pending-removal-in .. file.

So yeah I agree with Hugo, to have the detailed instructions in the devguide, and then add the .. seealso::
to the PEP.

[encukou]

IMO, a Process PEP should list the formal requirements, and the devguide should say how to meet them in practice. So, yes, please add this to Devguide! After that we can trim the PEP and have it link to devguide.

[Mariatta]

What is the workflow for "PendingDeprecationWarning"?

• When do we use it?
• What's the timeline for moving from PendingDeprecationWarning to DeprecationWarning?
• How do we track that it is time to upgrade the warning from PendingDeprecation to Deprecation?
• What docs are needed? Is there a pending-deprecariom-in-future?
• How does PendingDeprecationWarning appear on the "What's new in Python" doc?

[encukou]

AFAIK, we don't use PendingDeprecationWarning in CPython any more.