Document the workflow for deprecating something in CPython.

Abierto
#1,419 8 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

  • #1469 de @Lincoln-developer — cerrado sin fusionar

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
35/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
python
Área
documentation

Línea de trabajo

Empieza revisando el flujo de trabajo propuesto en este issue, la documentación de Porting y el archivo pending-removal-in....rst, incluido el rol deprecated-removed de Sphinx. El trabajo completado debe documentar la decisión de deprecación, las advertencias y las indicaciones de portabilidad, el momento de la eliminación, el proceso de feedback y el tratamiento de las deprecaciones sin una fecha de eliminación fija.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Python
Estrellas
2.1k
Forks
1k
Merge medio
2 d 12 h
PR fusionados (30 d)
12

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de python/devguide

Todos los issues de python/devguide

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.