Document the workflow for deprecating something in CPython. #1419
Description
Activity
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.
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.
Reacted by Mariatta and Petr ViktorinHmm, 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.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.
Reacted by Mariatta, Hugo van Kemenade and Alyssa CoghlanWhat 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?
AFAIK, we don't use PendingDeprecationWarning in CPython any more.
Reacted by Hugo van KemenadeHey @Mariatta I would love to work on this issue if no one is working on it. Thanks.
Hi @Lincoln-developer, yes please go ahead and create the PR.
- linked a pull request that will close this issueAdd a guide to deprecating features #1469on Nov 8, 2024
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:
Other info:
Note there is an open proposal for extending the removal of deprecated code to 5 years instead of 2.