Combien de temps attendre avant de supprimer une méthode obsolète? [fermé]

Je maintiens une API publique et 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 pour laquelle une méthode doit être déconseillée?

Au minimum, vous devez conserver les méthodes obsolètes dans une version avant de les supprimer, ce qui semble assez évident lorsque je l'écris. Je ne pense pas qu'il y ait une limite de temps, 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 doivent généralement pas contenir de modifications majeures. Comme l'a noté cHao dans les commentaires, la dépréciation ne signifie pas nécessairement qu'il y aura une suppression éventuelle. Par conséquent, si vous prévoyez de supprimer des éléments après la dépréciation, vous devez le noter explicitement et fournir des indications sur la chronologie.

Cela dépend uniquement du type de stabilité que vous avez donné à vos utilisateurs et de la douleur que vous souhaitez causer à vos utilisateurs.

Idéalement, votre API utilise semver de sorte que toute modification importante entraîne l’incrémentation du numéro de version principal. En pratique, il est souhaitable de le faire presque jamais. Si votre API est installée via un gestionnaire de paquets, vous pouvez créer un nouveau nom de paquet après une modification radicale, de sorte qu'une mise à niveau simple ne provoque pas de conflits (par exemple, myapi2 v2.123.4vs myapi3 v3.2.1). Cela peut être inutile si votre gestionnaire de paquets prend en charge des dépendances de version plus strictes (par exemple, une spécification de dépendance comme ~v2.120celle-ci n’inclut pas v3.*), mais différents noms de paquet présentent l’avantage que les versions incompatibles peuvent être utilisées très facilement côte à côte. Même en utilisant semver, il peut être judicieux d'avoir une période de désapprobation.

Semver n'est pas toujours applicable. Ensuite, il est plus important de communiquer une politique de stabilité claire. Par exemple:

• Les fonctions expérimentales peuvent être supprimées sans préavis.
• Les fonctionnalités peuvent être supprimées pour des raisons de sécurité à tout moment.
• Les autres fonctionnalités ne seront supprimées
  • … Après avoir été déconseillé dans une version publiée
  • … Où cette version a au moins trois mois
  • … Et sera marquée par une bosse dans la version majeure.

De telles stratégies fonctionnent particulièrement bien lorsque vous avez des mises à jour régulières, de sorte qu'une période de dépréciation, par exemple un an, est clairement définie.

En plus de marquer des parties de l'API comme étant déconseillées, vous devez largement faire connaître cette dépréciation. Par exemple:

• Avoir une section dans votre changelog sur les directions futures et les déprécations.
• Diffusez votre intention de déprécier avant d'exécuter la dépréciation et écoutez la communauté pour voir s'il y a des objections importantes.
• 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 constituer des supports appropriés. Faire un tour «nous créons une nouvelle fonctionnalité géniale! (qui nécessite la suppression de cette ancienne fonctionnalité largement utilisée) ”est un peu moins frustrant que de supprimer une fonctionnalité sans contexte.

En ce qui concerne la période de dépréciation exacte à choisir, commencez par vérifier si vous devez respecter les contrats de support avec vos utilisateurs. Ces contrats peuvent vous obliger à maintenir la compatibilité pendant un certain temps. Sinon, envisagez tout impact en aval. Essayez de changer moins rapidement que les utilisateurs en aval afin qu'ils puissent traverser leur propre cycle de dépréciation. Les utilisateurs en aval mettront un certain temps à s’adapter à vos modifications. Par conséquent, vous ne devriez jamais avoir une période de dépréciation inférieure à un mois.

Idéalement, vous voudriez attendre que personne n’utilise plus la méthode obsolète. Étant donné que vous utilisez une API publique, il est facile à suivre, mais vous risquez d'attendre très longtemps.

En 2015, Google avait un problème similaire avec l'API stlport sur leur système d'exploitation Android. Ils l'avaient obsolète et voulaient l'enlever, mais des tonnes d'applications l'utilisaient toujours. Ils ont trouvé une solution intelligente:

Essentiellement, ils ont ajouté une veille () de 8 secondes lors du démarrage de toute application utilisant encore l'API avec un message de journal approprié pour les développeurs. Un mois plus tard, ils l'ont doublé à 16 secondes. puis un autre mois plus tard, ils pouvaient supprimer en toute sécurité l'interface API car il ne restait plus personne à l'utiliser.

Cela peut être un moyen très efficace de le faire. Le seul problème réel est que votre API est très ancienne et a activement utilisé des consommateurs qui ne sont plus activement pris en charge. Malheureusement, vous ne pourrez probablement pas réparer vous-même ces consommateurs, mais à ce stade, vous ne pouvez pas vraiment faire plus que supprimer la méthode et casser le consommateur.

Le temps minimal requis pour fournir des méthodes obsolètes dépend des cycles de développement des programmes utilisant votre API. En chiffres approximatifs, un an devrait suffire.

En ce qui concerne le temps maximum avant que vous deviez supprimer les méthodes obsolètes, je dirais qu'il n'en est rien. Peu importe combien de temps 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 une compatibilité brisée signifiera la fin de vie de tels programmes.

Je vous suggère de supprimer les méthodes obsolètes lorsque vous retirez quelque chose de cette 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 de maintenir des méthodes obsolètes nécessiterait des efforts considérables
• vous optimisez la structure interne de votre bibliothèque et les méthodes obsolètes ne sont plus adaptées.

Supprimer des méthodes obsolètes simplement parce qu'elles le sont depuis X mois ou des années ou parce que vous publiez une nouvelle version revient à endommager la compatibilité de manière arbitraire, sans motif valable.

Tout d'abord, vous devez déterminer si vous souhaitez obsolète ou obsolète.

Obsolète devrait être utilisé pour les méthodes nuisibles: sécurité, performances, résultats incorrects. Vous voulez vous en débarrasser relativement rapidement, pas plus de 2 versions majeures et disparues à la 3ème. Obsolète peut être supprimé de la prochaine version mineure si le nombre de problèmes est suffisamment important.

Obsolète concerne les éléments moins utiles pour une raison quelconque, par exemple, renvoie 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 propagent depuis deux décennies parce que Microsoft croyait très fermement en la compatibilité ascendante.

De l'autre côté du spectre, de nombreuses applications Web suppriment des fonctionnalités sans même fournir un avertissement de dépréciation.

Combien vos clients paient pour votre logiciel sont souvent importants, tout comme leur travail. Les chercheurs scientifiques sont généralement plus enclins à accepter la dépréciation dans le cadre de la marche du progrès que, par exemple, 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 retourner dans les fichiers il y a 5 à 10 ans et les analyser sur des échelles de temps trop rapides pour permettre aux développeurs de réintroduire des fonctionnalités. L'attitude de l'un des groupes était: peut les trouver plus tard. " Au milieu, nous avions un groupe dont la règle était "Les fonctionnalités doivent être obsolètes pour au moins une 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 publions une nouvelle version, ils ont rapidement exécuté leur suite de tests pour voir si l'une des déprécations leur posait problème.

Je maintiens une API publique et dois déprécier une méthode.

Pourquoi avez-vous besoin de faire cela? Est-ce parce qu'il y a une nouvelle façon brillante de faire les choses, alors 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 peut rester en place, elle peut également l'être. Si ce n'est pas cassé, ne le répare pas. Avez-vous vraiment besoin de l'enlever? Peut-être le marquer comme obsolète et inclure dans la documentation une note indiquant qu'une autre méthode pourrait être plus efficace, ou peu importe, mais il est probablement préférable de la laisser en place.

• Si l'ancienne méthode doit vraiment disparaître, parce qu'elle vous cause des problèmes de maintenance ou qu'elle n'a tout simplement plus de sens en raison d'autres modifications, surveillez son utilisation et communiquez clairement la dépréciation aux clients. Donnez-leur une date précise après laquelle la méthode sera supprimée. (Idéalement, ne le retirez pas immédiatement à cette date: attendez que plus personne ne l’utilise encore avant de le retirer. Il faudra peut-être le faire plus tôt, si cela pose vraiment problème, mais attendez au moins que l’utilisation cesse peu.)

• Si l'ancienne méthode pose des problèmes de sécurité, vous devrez peut-être vous déplacer plus rapidement, voire même la supprimer sans avertissement, mais vous devriez documenter cette modification dans un endroit très visible et renvoyer des messages sensibles aux clients qui tentent d'utiliser l'ancienne méthode.

(Les deux autres points sont bien traités dans d'autres réponses, mais je pense que le premier est nouveau.)

Pour un projet public, ne le supprimez que si et seulement si vous en aviez besoin.

Lorsque vous supprimez des API de manière inutile, les entreprises et les sous-traitants coûtent de l’argent de telle sorte 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? Casse suffisamment leurs affaires quand tu n'es pas indispensable et que tu seras dans ce bateau en un rien de temps.

deprecation != eventual_removal. Si une API est dangereuse, vous la supprimez. Si c'est juste vieux, laissez-le et documentez son remplacement.