python / python/cpython

Enforce the use of `deprecated-removed` in docs

Abierto
#92,564 12 comentarios 2 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

3.10 3.11 3.12 3.9 (EOL) docs type-feature
Lenguaje dominante
Python
Estrellas
77.2k
Forks
36k
Merge medio
1 d 9 h
PR fusionados (30 d)
558

Descripción

In the docs we have two directives that can be used to document deprecations: deprecated and deprecated-removed.

I think we should always prefer the latter:

  • it will make it easier to track and document removals
  • it will give people a target, so they can plan around it

Even if the removal version gets postponed, it's better to postpone than to say that something is deprecated and then just remove it at an unspecified time in the future.

Currently deprecated is more commonly used:

$ grep -r 'deprecated::' --include=*.rst | wc -l
226
$ grep -r 'deprecated-removed::' --include=*.rst | wc -l
30
  • set removal version for deprecated features using deprecated-removed
  • automate the documentation of deprecations (see also #92308)
  • possibly deprecate the deprecated directive and replace it with deprecated-removed

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.

Línea de trabajo

Comienza volviendo a ejecutar los recuentos documentados de grep para deprecated:: y deprecated-removed:: en los archivos .rst; después, revisa el trabajo relacionado en #92308. La lista de comprobación del issue indica que, para completarlo, habría que establecer las versiones de eliminación, considerar la automatización y decidir si se debe marcar como obsoleta la directiva antigua.

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

Evaluación

Área
documentation
Tipo de issue
Documentación
Dificultad
5/5
Tiempo estimado
Más de una semana
Estado de actividad
Estancado
Claridad
Necesita aclaración
Aptitud para principiantes
25/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.