Combien de temps attendre avant de supprimer une méthode obsolète?
Je gère une API publique et je dois déprécier une méthode.
Existe-t-il une règle générale sur le nombre de mois/années/versions avant la suppression, je dois déconseiller une méthode?
Au minimum, vous devez conserver les méthodes obsolètes dans une seule version avant de les supprimer, ce qui semble assez évident lorsque je l'écris. Je ne pense pas qu'il y ait un temps maximum mais si vous ne les supprimez jamais, la dépréciation devient un peu inutile.
Les versions majeures sont un bon moment pour supprimer les méthodes obsolètes. Les versions mineures ne devraient généralement pas contenir de changements de rupture. Comme l'a noté cHao dans les commentaires, la dépréciation n'implique pas nécessairement qu'il y aura une suppression éventuelle, donc si vous prévoyez de supprimer des choses après la dépréciation, vous devez le noter explicitement et fournir des conseils sur le calendrier.
Cela dépend uniquement du type de garanties de stabilité que vous avez données à vos utilisateurs et de la douleur que vous souhaitez causer à vos utilisateurs.
Idéalement, votre API utilise semver de sorte que tout changement de rupture entraîne l'incrémentation du numéro de version principal. En pratique, il est souhaitable de ne le faire presque jamais. Si votre API est installée via un gestionnaire de packages, vous souhaiterez peut-être créer un nouveau nom de package après un changement de rupture afin qu'une simple mise à niveau ne provoque pas de conflits (par exemple myapi2 v2.123.4 contre myapi3 v3.2.1). Cela peut être inutile si votre gestionnaire de packages prend en charge des dépendances de version plus strictes (par exemple, une spécification de dépendance comme ~v2.120 qui n'inclut pas v3.*), mais les noms de packages différents ont l'avantage que les versions incompatibles peuvent être utilisées côte à côte très facilement. Même lorsque vous utilisez semver, il peut être judicieux d'avoir une période de dépréciation.
Semver n'est pas toujours applicable. Ensuite, il est plus important de communiquer une politique de stabilité claire. Par exemple:
- Les fonctionnalités expérimentales peuvent être supprimées sans préavis.
- Les fonctionnalités peuvent être supprimées à tout moment pour des raisons de sécurité.
- Les autres fonctionnalités ne seront supprimées que
- … Après avoir été déprécié dans une version publiée
- … Où cette version a au moins trois mois
- … Et sera marqué par une bosse dans la version majeure.
De telles politiques fonctionnent particulièrement bien lorsque vous avez des versions régulières afin qu'il y ait une période de dépréciation claire, par exemple un ans.
En plus de marquer toutes les parties de l'API comme obsolètes, vous devez faire largement connaître la dépréciation. Par exemple:
- Ayez une section dans votre changelog sur les directions futures et les dépréciations.
- Diffusez votre intention de déprécier avant de procéder à la dépréciation, et écoutez la communauté pour voir s'il y a des objections substantielles.
- Communiquez quels avantages découleront de ces changements. Selon votre base d'utilisateurs, les bulletins d'information, les présentations, les articles de blog ou les communiqués de presse peuvent être des supports appropriés. Avoir un spin “nous créons une nouvelle fonctionnalité impressionnante! (qui nécessite la suppression de cette ancienne fonctionnalité largement utilisée) "est un peu moins frustrant que la suppression d'une fonctionnalité sans contexte.
En ce qui concerne la période de dépréciation exacte à choisir, vérifiez d'abord si vous devez honorer tout contrat de support avec vos utilisateurs. Ces contrats peuvent vous obliger à maintenir la compatibilité pendant une certaine période. Sinon, tenez compte de tout impact en aval. Essayez de changer moins rapidement que les utilisateurs en aval afin qu'ils puissent passer par leur propre cycle de dépréciation. Les utilisateurs en aval mettront un certain temps à s'adapter à vos modifications, vous ne devriez donc jamais avoir une période de dépréciation inférieure à un mois.
Idéalement, vous voudriez attendre que plus personne n'utilise la méthode déconseillée. Étant donné que vous utilisez une API publique, c'est facile à suivre, mais vous pourriez finir par attendre très longtemps.
en 2015, Google a eu un problème similaire avec l'API stlport sur leur Android OS. Ils l'avaient déconseillé et voulaient le supprimer, mais des tonnes d'applications l'utilisaient toujours. Ils ont trouvé une solution intelligente :
Essentiellement, ils ont ajouté un sommeil de 8 secondes () lors du démarrage de toute application qui utilisait toujours l'API avec un message de journal approprié pour les développeurs. Un mois plus tard, ils l'ont doublé à 16 secondes. puis un mois plus tard, ils ont pu supprimer l'interface API en toute sécurité car personne n'était laissé l'utiliser.
Cela peut être un moyen très efficace de le faire. Le seul vrai problème est de savoir si votre API est très ancienne et a utilisé activement des consommateurs qui ne sont plus activement pris en charge. Malheureusement, vous ne pourrez probablement pas réparer vous-même de tels consommateurs, mais à ce stade, vous ne pouvez pas faire grand-chose de plus que supprimer la méthode et casser le consommateur.
Le temps minimum pour fournir des méthodes obsolètes dépend des cycles de développement des programmes utilisant votre API. Comme chiffre approximatif, 1 an devrait suffire.
En ce qui concerne le temps maximum avant de supprimer des méthodes obsolètes, je dirais qu'il n'y a rien de tel. Peu importe le temps que vous attendez, la suppression d'une méthode obsolète cassera toujours quelque chose. Certains programmes utilisant votre API obsolète ne sont pas activement maintenus, et la rupture de la compatibilité entraînera la fin de vie de ces programmes.
Je vous suggère de supprimer les méthodes obsolètes lorsque vous gagnez quelque chose de la suppression:
- un bogue est détecté qui affecte spécifiquement les méthodes obsolètes
- vous êtes sur le point de refactoriser le code et le maintien de méthodes obsolètes nécessiterait des efforts importants
- vous optimisez la structure interne de votre bibliothèque et les méthodes obsolètes ne conviennent plus.
La suppression de méthodes obsolètes simplement parce qu'elles sont obsolètes depuis X mois/années ou parce que vous publiez une nouvelle version revient à nuire arbitrairement à la compatibilité sans raison valable.
Vous devez d'abord vous demander si vous voulez obsolète ou obsolète.
Obsolète devrait être utilisé pour les méthodes qui sont en quelque sorte nuisibles: sécurité, performances, résultats incorrects. Vous voulez vous en débarrasser relativement rapidement, pas plus de 2 versions majeures et disparues par la 3e. Pour des problèmes suffisamment importants, les éléments obsolètes peuvent être supprimés dans la prochaine version mineure.
Obsolète est pour des choses qui sont moins utiles pour une raison quelconque, par exemple retourne moins d'informations ou ne fonctionne pas aussi bien, n'inclut pas autant d'options et ainsi de suite. Ceux-ci peuvent traîner indéfiniment, mais devraient au minimum être présents dans la prochaine version majeure.
La réponse dépend du type de service que vous offrez à vos clients.
À une extrémité de l'extrême, il y a des erreurs dans Windows.h de l'ère Win 3.1 qui se sont propagées pendant deux décennies parce que Microsoft croyait fermement en la compatibilité descendante.
À l'autre extrémité du spectre, de nombreuses applications Web suppriment des fonctionnalités sans même fournir un avertissement de dépréciation.
Le montant que vos clients paient pour votre logiciel est souvent important, tout comme leur travail. Les chercheurs sont généralement plus disposés à accepter la dépréciation dans le cadre de la marche du progrès que, disons, les banquiers ou la FAA.
J'ai travaillé pour une entreprise développant des logiciels à usage interne. J'ai soutenu de nombreux groupes au fil des ans. Un groupe avait une mentalité de "ne jamais supprimer aucune fonctionnalité". Ils avaient besoin de pouvoir revenir aux fichiers il y a 5 à 10 ans et faire une analyse sur eux à des échelles de temps trop rapides pour que les développeurs réintègrent les fonctionnalités. pourra les retrouver plus tard. " Au milieu, nous avions un groupe dont la règle était "Les fonctionnalités doivent être déconseillées pour au moins 1 version avec un avertissement imprimé si elles sont utilisées avant de les supprimer." Ce groupe avait une suite de tests qui couvrait les fonctionnalités dont ils avaient besoin. Chaque fois que nous avons publié une nouvelle version, ils ont rapidement exécuté leur suite de tests pour voir si l'une des dépréciations leur avait causé des problèmes.
Je gère une API publique et je dois déprécier une méthode.
Pourquoi avez-vous besoin de faire ça? Est-ce parce qu'il y a une nouvelle façon brillante de faire les choses, donc l'ancienne méthode est maintenant découragée, mais fonctionne toujours bien? Ou est-ce que l'ancienne méthode doit réellement disparaître parce que les choses ont fondamentalement changé?
Si l’ancienne méthode ne pose aucun problème réel et que peut rester, elle peut aussi bien. Si ce n'est pas cassé, ne le réparez pas. Avez-vous vraiment besoin de le supprimer? Peut-être le marquer comme obsolète, et inclure une note dans la documentation qu'une autre méthode pourrait être plus efficace, ou autre, mais c'est probablement bien de la laisser en place.
Si l'ancienne méthode doit vraiment disparaître, car elle vous cause des maux de tête de maintenance ou parce qu'elle n'a tout simplement plus de sens en raison d'autres changements, alors surveillez son utilisation et communiquez clairement la dépréciation aux clients. Donnez-leur une date claire après laquelle la méthode sera supprimée. (Idéalement, ne le supprimez pas immédiatement à cette date: attendez que personne ne l'utilise encore avant de le supprimer. Il faudra peut-être le faire plus tôt, si cela cause vraiment des problèmes, mais attendez au moins que l'utilisation abandonne un peu.)
Si l'ancienne méthode pose des problèmes de sécurité, vous devrez peut-être aller plus vite que cela, peut-être même la supprimer sans avertissement, mais vous devez documenter ce changement quelque part très visible, et renvoyer également des messages sensibles aux clients qui tentent d'utiliser l'ancienne méthode.
(Les deuxième et troisième puces sont bien couvertes dans d'autres réponses, mais je pense que la première est nouvelle.)
Pour un projet public, ne le supprimez que si et seulement si vous en avez besoin.
Lorsque vous effectuez une suppression d'API inutile, vous coûte de l'argent aux entreprises et aux entrepreneurs de telle manière que vous ne pouvez même pas calculer en raison d'un taux de désabonnement coûteux.
Vous voulez que les entreprises et les programmeurs indépendants cessent d'utiliser votre projet? Cassez leurs affaires suffisamment de fois lorsque vous n'êtes pas essentiel et vous serez dans ce bateau en un rien de temps.
deprecation != eventual_removal. Si une API est dangereuse, vous la supprimez. S'il est juste vieux, laissez-le et documentez son remplacement.