Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Document the workflow for deprecating something in CPython. #1419

Open
Mariatta opened this issue Sep 27, 2024 · 8 comments · May be fixed by #1469
Open

Document the workflow for deprecating something in CPython. #1419

Mariatta opened this issue Sep 27, 2024 · 8 comments · May be fixed by #1469

Comments

@Mariatta
Copy link
Member

Mariatta commented Sep 27, 2024 •
edited
Loading

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
Copy link
Member

encukou commented Sep 27, 2024

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
Copy link
Member

hugovk commented Sep 27, 2024

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
Copy link
Member Author

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
Copy link
Member

encukou commented Sep 27, 2024

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
Copy link
Member Author

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
Copy link
Member

encukou commented Oct 1, 2024

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

@Lincoln-developer
Copy link
Contributor

Hey @Mariatta I would love to work on this issue if no one is working on it. Thanks.

@Mariatta
Copy link
Member Author

Mariatta commented Nov 5, 2024

Hi @Lincoln-developer, yes please go ahead and create the PR.

@AA-Turner AA-Turner linked a pull request Nov 8, 2024 that will close this issue
Add a guide to deprecating features #1469
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add a guide to deprecating features Lincoln-developer/devguide
4 participants
@encukou @hugovk @Mariatta @Lincoln-developer