Comment annoncer des modifications rétrocompatibles dans un projet OSS ?

Question

Parfois, vous devez introduire des modifications rétrocompatibles, lorsque les améliorations dépassent de loin les inconvénients.Il est possible de revenir facilement à l'ancien comportement, mais l'utilisateur doit être conscient de ces changements.

La question est donc : comment annoncer les futures modifications rétrocompatibles du projet FLOSS (open source), afin que les utilisateurs puissent s'y préparer et soit modifier leur utilisation, soit configurer le programme pour qu'il utilise l'ancien comportement.

Puisqu'il s'agit d'un projet OSS, il est fourni indépendamment par diverses distributions et peut être mis à niveau automatiquement sans intervention de l'utilisateur.Et puis, une modification rétrocompatible pourrait perturber le flux de travail de quelqu'un (scripts tiers par exemple).

Pistes actuellement envisagées (et utilisées) :

• liste de diffusion du projet
• page d'accueil du projet
• notes de version (premier avertissement, puis annonce)
• blog du responsable

Modifier 1 : Ce changement (rétrocompatible) se produirait dans certains majeur libérer.

Tous les changements consistent soit à ajouter des protections (en refusant les commandes qui peuvent complètement dérouter les utilisateurs débutants), soit à modifier les valeurs par défaut pour des valeurs plus saines.

Modifier 2 : Pendant la période de transition, la configuration par défaut (qui est censée être modifiée par défaut refuser/refuser) est remplacée par avertir, avec une description de la manière de désactiver un avertissement, ce qui protégerait également contre les modifications rétrocompatibles du comportement par défaut.

Mais s'il s'agit d'un système automatisé, cela pourrait ne pas aider...

---

Le projet en question est Git, système de contrôle de version distribué ;
voir Donner une alerte précoce aux utilisateurs à le journal de Gitster (Blog Junio ​​C Hamano)

Answer 1

• Changer la majeure du numéro de version
• Annoncez-le par toutes les voies à votre disposition
• Ajouter une annonce importante dans le fichier Lisez-moi
• Ajoutez du code qui convertit entre l'ancien et le nouveau si la base de données ou d'autres modifications sont nécessaires
• Ajoutez du code qui détecte l'utilisation de méthodes dépréciées, de stockage de données, etc. et alerte l'utilisateur avant d'effectuer des modifications destructrices
• Posez des questions pertinentes de type FAQ sur les principaux sites Web de questions/réponses. Ainsi, lorsque les gens ont des questions, la réponse est immédiate et évidente à l'aide d'une simple recherche.

Mais le numéro de version majeure est la cible principale : les utilisateurs s'attendent à ce que les transitions 1.x vers 2.x provoquent des problèmes et sont plus prudents lors de la mise à niveau.

-Adam

Answer 2

Vous avez de bonnes réponses pour faire passer le message.Mais migrer mon propre état d’esprit est le plus gros problème pour moi, en particulier lorsque les fonctions obsolètes se trouvent dans ma mémoire musculaire.Désapprendre est plus difficile qu’apprendre.

Recevoir des avertissements en cas d'incompatibilités à venir quand j'utilise réellement les commandes qui vont changer est particulièrement utile, en particulier avec les modifications des valeurs par défaut.Quelque chose comme:

 $ git foo  
 Note: git foo currently defaults to HEAD. Starting with
 version 2.0, git foo will instead default to master.

Answer 3

Je pourrais opter pour RSS (s'il existe), Twitter (s'il existe), une liste de diffusion (envoyer au moins 3 messages à mesure que la mise à jour approche), une page d'accueil (la rendre très contrastée pour qu'elle soit facile à voir) et un blog, bien sûr. .les notes de version sont à peine lues, alors prenez-les comme dernier point d'information.

(J'ai posté ceci comme première réponse, mais je ne me suis pas présenté)

Answer 4

Tout ce qui précède plus.

Si vous avez un changement où :

La syntaxe exacte d'une commande non destructive changerait pour devenir une commande destructive

Je ne vois pas d'autre choix que de faire le changement à la place plus perturbateur pour rendre l'ancienne commande totalement invalide, de sorte que si un utilisateur met à niveau et tente (ou très probablement un script tente) l'ancienne commande, il se termine par un message d'erreur descriptif sur stderr.Utiliser stderr pour les messages d'avertissement sur les commandes avec des changements subtils (ou moins subtils) qui ne sont pas destructifs est également une bonne idée.La définition de destructeur est un peu plus complexe sur un référentiel source

Utiliser les avertissements stderr pour des méthodes de dépréciation simples est souvent une bonne chose, mais certaines personnes se plaindront que cela casse leurs scripts (mal écrits).Dans ces cas, une version silencieuse de dépréciation (toutes les formes non invasives de dépréciation) suivie d'une version verbale (avertissements stderr) suivie peut-être (voir ci-dessous) d'une version non fonctionnelle mais présente, suivie ensuite d'une suppression totale.Cette dernière version non fonctionnelle dépendra fortement du projet en question car elle pourrait poser plus de problèmes qu'elle n'en vaut la peine, en particulier pour les utilisateurs qui se comportent bien et se tiennent au courant des fonctionnalités obsolètes.

Étant donné que le changement spécifique auquel vous faites référence est la suppression des éléments intégrés, cela devrait aller. Je n'aurais probablement pas fait une seule version avec les éléments intégrés dans un mode non fonctionnel, mais je ne connais pas assez bien le projet pour le dire avec certitude. .

Remarque pour code plutôt que des changements au niveau du script, il est possible dans de nombreux langages modernes de laisser des stubs de méthode avec des attributs/annotations qui les masqueront entièrement à Intellisense et refuseront de compiler avec eux.Cela fait de leur présence (avec une simple exception si elle est utilisée) un moyen bien plus agréable de découvrir que vous ne pouvez pas les utiliser qu'une MissingMethodException d'exécution ou autre.

Answer 5

Juste mes 0,02 $.Les environnements de développement modernes (en particulier .NET) fournissent des moyens de signaler au développeur que certaines API sont déclarées obsolètes/obsolètes et seront supprimées dans les versions futures.Le compilateur Microsoft C/C++ a #pragma obsolète.

Si rien de tout cela n'est pris en charge dans votre environnement, comptez sur gestion des versions pour fournir des commentaires sur la compatibilité.