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


38

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?


27
La règle générale est "conservez-le aussi longtemps que vous et / ou vos clients en avez besoin".
Robert Harvey

15
Définir "public". Logiciel libre et open source, avec le déni de responsabilité habituel "utilisez-le à vos risques et périls"? Ou un logiciel vendu où un contrat existe?
Doc Brown

11
Cela dépend beaucoup du marché de vos utilisateurs et de la question de savoir s'ils vous paient de l'argent pour l'API.
17 du 26

10
Cela dépend aussi de la raison pour laquelle vous "devez" l'amortir; L'ancienne manière est-elle un risque pour la sécurité? Avez-vous trouvé maintenant une raison pour laquelle l'ancienne méthode est fondamentalement instable et instable en raison d'une décision de conception malheureuse? L'ancienne voie est-elle beaucoup plus lente maintenant qu'elle ne l'était? Êtes-vous à court de mémoire sur votre système cible (par exemple, un système intégré) et vous ne pouvez littéralement pas y insérer les deux API? Ou avez-vous simplement trouvé un "meilleur" moyen et souhaitez-vous simplement effacer l'ancien code afin de réduire vos coûts de maintenance?
Jrh

8
java.io.StringBufferInputStreamobsolète depuis JDK 1.1 (1997?). Il n'y a pas de bonne ou de mauvaise réponse à cette question. Cela dépend de vos besoins en matière de compatibilité ascendante.
Laiv

Réponses:


52

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.


58
La déprécation ne concerne pas nécessairement la suppression éventuelle, aussi la dépréciation sans suppression est-elle inutile (et est souvent la bonne chose si la compatibilité ascendante est importante). Souvent, l’objet n’est rien de plus que "nous avons une meilleure solution maintenant, vous ne devriez donc plus le faire de cette façon".
cHao

9
@cHao Si quelque chose est déconseillé, vous ne devriez pas vous attendre à ce qu'il continue d'être là. Je suppose que si vous souhaitez faire une déclaration spéciale dans votre projet qui indique que vous ne supprimerez pas les fonctionnalités obsolètes, c'est correct, mais sinon, oui, il est implicite qu'il y aura une suppression éventuelle. Ce que je veux dire, c'est que si vous ne maintenez pas une sorte de rigueur à cet égard, les gens finiront peut-être par croire que cela ne se produira jamais. Il en est résulté des versions récentes de Java dans lesquelles des fonctionnalités obsolètes depuis une décennie ou plus sont maintenant supprimées.
JimmyJames

6
@ cHao Je préférerais qu'un projet supprime ses fonctionnalités obsolètes. Non seulement les utilisateurs sont réellement motivés à changer, mais cela empêche également l'interface obsolète d'interférer avec d'autres améliorations.
jpmc26

9
@ cHao C'est une chose sensible au contexte. D'après mon expérience, la politique de dépréciation est claire. Il est clairement indiqué que les fonctionnalités obsolètes seront supprimées à un moment donné. Les fonctionnalités souvent déconseillées posent des problèmes qui rendent son utilisation problématique, et il ne s'agit pas simplement de savoir si vous accordez de l'importance à la compatibilité ascendante ou non.
JimmyJames

6
Je vais me mettre d'accord avec @JimmyJames sur le fait que la dépréciation implique clairement un retrait imminent. La période de désapprobation existe afin de fournir une compatibilité ascendante temporaire afin que les consommateurs puissent migrer vers la nouvelle fonctionnalité. Il ne faut absolument pas s'attendre à ce que la fonctionnalité déconseillée reste indéfiniment. Si l'ancienne fonctionnalité doit rester, il n'y a aucune raison de la déconseiller.
Eric King

17

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.


3
En raison de ceci: à Ideally, your API uses semver so that any breaking change causes the major version number to be incremented. In practice, it is desirable to do this almost never.quoi sert-il d'utiliser semver pour indiquer des changements radicaux si vous suivez cela en disant que vous ne devriez jamais introduire de nouvelle version majeure?
mrsmn

6
Est-ce vraiment une bonne idée de renommer le paquet en cas de changement majeur? C'est à quoi servent les numéros de version. Je déteste quand ils les renomment également, cela gâche vraiment la gestion des dépendances Maven.
AJPerez

@AJPerez Je comprends que ce n'est pas idéal, mais cela peut éviter les conflits dans les grands graphes de dépendance avec dépendances transitives: je dépend de libfoo, qui dépend de libconflict v1.2.3, et de libbar, qui dépend de libconflict v2.3.4. Ensuite, je ne peux sélectionner aucune version de libconflict qui réponde à toutes les dépendances - à moins que libconflict et libconflict2 ne soient des packages distincts. Spécifiquement pour Java, un tel changement de nom est ennuyeux car je dois modifier toutes les importations. Heureusement, Java 9 (modules) prend en charge l’utilisation de versions en conflit.
amon

1
@mrsmn Les changements de rupture sont ennuyeux, mais vous les créez ou les nommez. Semver n'aborde qu'une petite partie de ce problème: être capable de dire si une mise à jour va casser quelque chose. Mais une fois que vous avez eu un changement radical, vous devez encore déployer des efforts considérables pour tenir compte de ce changement. Par conséquent, il est préférable que les API s'efforcent d'être aussi stables que possible. Idéalement, ils sont conçus de manière à pouvoir être étendus sans rupture de compatibilité ascendante.
amon

@AJPerez oui. Oui, c'est bon. Les gens bousillent tout le temps la gestion des versions. Les correctifs de bogues (supposés xxx ++) se brisent souvent (supposés x ++. Xx). Comme amon points sur vous (et je ne veux vous en tant qu'utilisateur de la dépendance) ont un problème que vous devez fixer. Je sais que mon code fonctionne avec foo 3.2.1 et peut-être avec foo 3.3.0. Je sais que mon code fonctionne avec foo, il peut fonctionner avec foo-2. J'utilise semver parce que la popularité ne me fait pas mal, mais ce n'est pas clair pour moi que cela vous achète beaucoup.
Jared Smith

14

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:

entrez la description de l'image ici

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.


5
Mignonne. Très mignon.
David Hammen

8

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.


7

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.


Je dirais qu'une méthode donnant des résultats incorrects ou nuisant à la sécurité devrait être soit désactivée immédiatement, soit corrigée. Une méthode présentant de mauvaises performances peut persister indéfiniment, à condition que ses performances soient acceptables pour certains utilisateurs.
Dmitry Grigoryev

@DmitryGrigoryev: une version mineure simple est presque immédiatement immédiate.
Jmoreno

4

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.


4

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.)


1

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.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.