Enforce the use of `deprecated-removed` in docs

Ouverte
#92,564 12 commentaires 2 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
25/100
Type d'issue
Documentation
Clarté
À clarifier
Activité
À l'abandon
Domaine
documentation

Piste de recherche

Commencez par relancer les comptages grep documentés pour deprecated:: et deprecated-removed:: dans les fichiers .rst, puis examinez le travail associé dans #92308. La checklist de l'issue indique que sa finalisation nécessiterait de définir les versions de suppression, d'envisager l'automatisation et de décider s'il faut déprécier l'ancienne directive.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

3.10 3.11 3.12 3.9 (EOL) docs type-feature

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
Langage dominant
Python
Étoiles
77.2k
Forks
36k
Merge moyen
1 j 9 h
PR mergées (30 j)
558

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de python/cpython

Toutes les issues de python/cpython

Issues similaires

Plus d'issues Python

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.