python / python/devguide

Document the workflow for deprecating something in CPython.

Offen
#1,419 8 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

  • #1469 von @Lincoln-developer — ohne Merge geschlossen
Vorherrschende Sprache
Python
Sterne
2.1k
Forks
1k
Ø Merge
2 T. 12 Std.
Gemergte PRs (30 T.)
12

Beschreibung

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.

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne mit der Durchsicht des in diesem Issue vorgeschlagenen Workflows, der Porting-Dokumentation und der Datei pending-removal-in....rst, einschließlich der deprecated-removed Sphinx-Rolle. Die abgeschlossene Arbeit sollte die Deprecation-Entscheidung, die Warnungs- und Porting-Hinweise, den Zeitpunkt der Entfernung, den Feedback-Prozess und den Umgang mit Deprecations ohne festgelegtes Entfernungsdatum dokumentieren.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.