Déprécier une fonction dans une bibliothèque : avertir, documenter le remplacement, supprimer selon un calendrier

Objectif

Supprimer ou modifier une fonction, une classe ou une option publique d'une bibliothèque sans casser les utilisateurs entre deux versions consécutives, et sans porter l'ancien chemin indéfiniment. Il s'agit du pendant, côté bibliothèque, de la dépréciation d'un point de terminaison HTTP (article lié), avec des avertissements et une politique de version en lieu et place des en-têtes.

Prérequis

Une définition de ce qui est public. La PEP 387 considère comme publics les noms, les positions et types des arguments, les valeurs de retour et les exceptions levées, et exclut les noms préfixés d'un tiret bas ainsi que tout ce qui est documenté comme privé ; un nom non documenté n'est pas automatiquement privé. Une politique de cadence écrite, car la date de suppression s'exprime en nombre de versions.

Étapes

1. Livrer d'abord le remplacement, dans une version qui prend encore en charge l'ancien chemin sans changement, afin que la migration ne soit qu'une seule étape.
2. Marquer l'ancien chemin dans la même version ou la suivante : un avertissement à l'exécution de la catégorie dépréciation, une note dans la documentation de référence indiquant la version de dépréciation et le remplacement, et une entrée sous une rubrique « Déprécié » dans le journal des modifications.
3. Fixer la version de suppression par politique plutôt qu'au cas par cas. La PEP 387 indique qu'un changement incompatible doit suivre le processus de dépréciation, que la cadence annuelle implique au moins deux ans entre l'avertissement et la suppression, et (depuis une modification de 2025) que cinq ans sont préférables ; la politique de Django maintient une fonctionnalité dépréciée en fonctionnement pendant toutes les versions de la série majeure en cours et la supprime dans la version majeure suivante, ou une version plus tard, de sorte qu'au moins deux versions fonctionnelles séparent l'avertissement de la suppression. Un petit projet peut adopter la règle « supprimé au plus tôt à la deuxième version fonctionnelle suivant l'avertissement ».
4. Rendre l'avertissement visible là où cela compte. Le filtre par défaut de Python ignore DeprecationWarning, sauf lorsqu'il est déclenché directement par du code dans __main__ ; la documentation recommande aux lanceurs de tests d'afficher tous les avertissements pour le code testé. Exécuter la propre suite de tests de la bibliothèque en transformant les avertissements en erreurs, afin que les usages internes de l'ancien chemin apparaissent en premier.
5. Préférer une dépréciation douce lorsque l'ancien chemin peut être conservé sans risque : la PEP 387 la décrit comme documentée, testée, non développée davantage, et sans suppression programmée ni avertissement.
6. Supprimer dans la version annoncée, la lister sous la rubrique « Supprimé » du journal des modifications, et incrémenter la version selon la politique de versionnage (une version majeure sous le versionnage sémantique).

Résultat attendu

Les utilisateurs voient un avertissement par ancien site d'appel pointant vers le remplacement, et savent dans quelle version il disparaîtra ; la bibliothèque ne porte chaque rustine de compatibilité que pour un nombre borné de versions.

Limites et base de vérification

Les politiques sont citées d'après les documents Python et Django mentionnés ; un projet avec une cadence différente doit traduire « deux versions » dans son propre calendrier. Aucun résultat de migration n'est mesuré.