L'historique de validation doit-il être utilisé pour transmettre des informations critiques aux développeurs?

Lors d'une réunion sur la restauration d'un SDK tiers à partir de la dernière version, il a été noté que nos développeurs avaient déjà signalé dans l'historique des validations que la dernière version ne devait pas être utilisée.

Certains développeurs ont fait valoir que c'était une mauvaise pratique et que cela aurait dû plutôt être noté soit dans le fichier source (c.-à-d. // Don't upgrade SDK Version x.y.z, see ticket 1234), Soit dans un READMEfichier au niveau du projet . D'autres ont fait valoir que l'historique des validations faisant partie de la documentation du projet, il s'agissait d'un emplacement acceptable pour de telles informations, car nous devrions tous les lire.

L'historique de validation doit-il être utilisé pour transmettre des informations critiques à d'autres développeurs ou doit-il être dupliqué vers un autre emplacement, tel qu'un projet READMEou des commentaires dans le fichier source approprié?

Si je devais envisager de mettre à niveau une version plus récente d'un kit de développement logiciel ( SDK) tiers, le dernier endroit que je regarderais se trouve dans l' historique du système de contrôle de code source.

Si votre produit utilise la version 2.0 d'un SDK et que quelqu'un souhaite passer à la version 3.0, je ne pense pas qu'il soit raisonnable de penser qu'il devrait regarder en arrière dans le temps dans votre système de contrôle de source pour découvrir que ce n'est pas une bonne idée.

Ici, nous avons un wiki d'équipe qui contient une poignée de pages avec des informations intéressantes lues par tous les développeurs (conventions de codage, configuration d'un environnement de développement pour la création du produit, éléments tiers à installer, etc.). C’est le genre d’endroit qui convient pour mettre en garde contre la mise à niveau d’une bibliothèque tierce.

Cela devrait être noté dans l'historique de validation, mais le meilleur endroit pour placer la notification est au même endroit que vous définissez la dépendance. Si vous avez par exemple un fichier .pom maven qui déclare vos dépendances d'artefact, je ferais quelque chose comme:

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

Directement au-dessus de votre <dependency>ligne.

Le numéro 123 inclurait des détails sur la façon dont il se bloque, la version mise à jour qui a provoqué le crash, et il devrait probablement être ajouté à votre carnet de commandes pour une nouvelle consultation. Il est possible qu'une version encore plus récente corrige le problème. Soit automatiquement en éditant le ticket, soit manuellement vous-même, il enverra un e-mail à l'équipe pour l'informer maintenant du problème en cours et, en étant dans le suivi, il permettra aux gens de le retrouver plus tard.

La raison pour la mettre avec la déclaration de dépendance est que quiconque veut changer de version le verra au moment où il veut le changer et comprend pourquoi il ne devrait pas le faire.

Je ne commenterais pas le code source car je peux facilement imaginer une situation dans laquelle une personne vérifie vos dépendances et commence à les mettre à niveau. Ils ne devraient pas avoir besoin de parcourir le code pour chaque commentaire TODO.

La liaison au ticket de sortie permet à un développeur curieux de savoir comment cela a échoué et de le revoir ultérieurement. Sans cela, il pourrait devenir assez statique et ne plus jamais être mis à jour.

Les éléments d'information critiques et non intuitifs doivent être documentés à l'endroit où les gens regarderont lors de l'examen de l'information.

Pour les équipes et les projets sur lesquels j'ai travaillé, j'engagerais la restauration en expliquant pourquoi la nouvelle version avait échoué. J'ajouterais une histoire en retard pour réessayer la mise à niveau si la nouvelle version est corrigée. J'ajouterais des commentaires aux scripts de construction / système de construction où la bibliothèque est liée.

Cette annulation fournira un contexte aux futurs développeurs lorsqu'ils examineront l'historique du projet. L'historique du backlog conserve la nécessité de cette mise à niveau en tant que partie active du projet. Les commentaires du système de construction sont exactement là où les modifications devront être apportées lorsque la bibliothèque sera finalement mise à jour.

Je ne le commenterais pas dans le code et je ne l'ajouterais pas à un fichier LISEZMOI. Les développeurs qui envisagent d’essayer la mise à niveau ne se pencheront pas sur ces éléments. Si vous l'ajoutez ici, lorsque le problème avec la bibliothèque sera résolu et qu'une mise à niveau sera effectuée, vous devrez le supprimer. Cette étape est souvent oubliée: il en résulte des notes contre-productives pour le projet.

Si votre projet a une configuration différente ou un flux différent, votre réponse peut être différente. Je pense que la clé est de corriger les informations si le développeur les voit lors de l'exécution du travail de mise à niveau. De cette façon, si le moment n'est pas propice à la mise à niveau, le développeur le verra et s'arrêtera. Lorsque le moment sera venu, le développeur le verra et supprimera la note afin d'éviter toute confusion pour les futurs développeurs.

Je voulais donner plus d'attention au commentaire de Matthew en soulignant son idée importante dans une réponse. Il y a une raison pour laquelle vous ne souhaitez pas mettre à niveau votre SDK et cette raison doit être capturée dans un test unitaire. Pas une vérification pour un numéro de révision, mais la raison sous-jacente réelle.

Par exemple, supposons qu'il y ait un bogue dans la nouvelle version. Ecrivez un test unitaire qui recherche ce bogue. S'ils corrigent ultérieurement ce bogue dans le SDK, la mise à niveau se déroulera sans heurts. En cas de modification de l'API incompatible, écrivez un test vérifiant que votre code prend en charge la nouvelle API ou que le kit SDK prend en charge l'ancienne. Il s’agit plus d’un test d’intégration que d’un test unitaire, mais cela devrait quand même être faisable.

Mon entreprise génère plus de 50 validations par jour et nous ne sommes pas vraiment énormes. Même si chaque développeur lit chaque message de validation, ce qui est honnête, la raison pour laquelle nous avons besoin d'une histoire de validation enregistrée est que les utilisateurs ne peuvent pas s'en souvenir. Et les gens ne reviennent pas et ne lisent l'histoire plus tard que s'il y a un problème. Et ils n'ont aucune raison de suspecter un problème sur une mise à niveau qui, à leur connaissance, n'a pas encore eu lieu.

Bien sûr, envoyez un email pour éviter la duplication de travail à court terme, et notez-le dans vos scripts de construction et dans un fichier README ou des errata. Cependant, surtout si le problème avec la nouvelle version prend du temps à résoudre, il vous faut un moyen de le rendre évident. Cela signifie un test unitaire.

Je reformule la question comme suit: "Devrais-je communiquer des informations critiques que je découvre au reste de l'équipe uniquement via un message de validation?" Parce que je pense que cela rend évident que non, vous ne devriez pas. Je fais de gros efforts pour communiquer beaucoup (c’est quelque chose que la plupart des équipes de développement doivent, selon mon expérience, faire des efforts actifs) et je fais tout ce qui est en mon pouvoir pour éviter de créer des pièges ou de les laisser mentir.

Si la chaîne d'actions menant à une telle découverte était déclenchée par un ticket, je mettrais à jour le ticket (et m'assurerais que les personnes qui devraient le savoir ont de la visibilité), je le mentionnerais probablement face à face (en espérant laisser au moins quelqu'un avec un sentiment perspicace que "Gee, je pense que Damon a dit quelque chose à propos de cette mise à jour"), et je laisserais bien sûr un commentaire dans le code au point où le SDK a été inclus afin que personne ne puisse éventuellement mettre à jour sans avoir la chance de le voir. Je verrais peut-être si je pouvais l'enregistrer quelque part sur notre dev wiki, bien que cela soit davantage axé sur les recrutements futurs, et non sur l'équipe actuelle.

Cela ne prend que quelques minutes de plus par rapport au temps qu'il a probablement fallu pour rencontrer et découvrir le problème. Je n’aurais certainement pas décidé que l’un des éléments les moins utilisés et les moins signalés de notre documentation et en resterait là.

Cela devrait être dans l'historique de validation, mais pas seulement dans l'historique de validation, imaginez un instant que vous embauchiez un nouveau développeur. Vous attendez-vous à ce que le nouveau développeur lise chaque message de validation des 10 dernières années de votre projet, car deux d'entre eux seront essentiels à la compréhension de votre base de code?

Deuxièmement, dites-vous que la situation, mais pas les modifications de code, est-ce que vous allez faire des "commits de documentation" afin que vous puissiez ajouter des messages de commit comme suit: "le message de commit de la révision 5432 est maintenant incorrect, voici la situation actuelle".

Je ne suis pas sûr de la manière dont votre équipe communique mais je pense que le moyen le plus efficace de le dire est d' envoyer d' abord un e-mail au groupe de messagerie de l'équipe, identifié par "URGENT" avec le corps en disant

Les gars, nous ne pouvons pas utiliser SDK v xyz car le tampon Foo risque de déborder et le service Bar se bloquera. Coller avec la version xyy

C'est ce que nous avons fait ici et c'est le moyen le plus fiable de faire passer le message. Si vous voulez vraiment être difficile (et si votre système de messagerie le permet), demandez un "accusé de lecture" sur le message.

Une fois que vous avez informé toute l'équipe, une documentation plus détaillée doit être placée dans un wiki d'équipe. Cela varie en fonction de la structure de votre documentation. Si vous avez une section spécifique à vos applications Dépendances et exigences, ce serait un bon endroit pour l'ajouter.

Un endroit supplémentaire pour documenter ce type de problème pourrait être dans le code source lui-même, bien que cela ne fonctionne pas toujours. Si SDK version ...n'est référencé que dans un ou deux endroits évidents, vous pouvez inclure une note sur la non mise à niveau.

L’historique des fichiers dans le contrôle de source peut être très long et, selon les développeurs, avoir plusieurs entrées par jour. Quelqu'un qui est en vacances depuis une semaine n'a peut-être pas le temps de lire une semaine d'histoire. Le fichier README est un meilleur endroit car il est un peu plus central et les gens sont peut-être plus enclins à le lire, mais vous ne pouvez pas vous assurer que tout le monde lira réellement le README. Eh bien, je suppose qu’ils pourraient le faire s’ils voient que cela a été changé ...

Quelque chose comme cela aurait dû figurer dans les commentaires de commit, mais il serait également avantageux de se trouver ailleurs.

Quiconque prend la décision de mettre à niveau, doit avoir les faits. Cette personne ne peut pas vivre dans le contrôle de source. Et si quelqu'un aurait lu ce problème sur SO et ne l'a jamais mis dans la base de code?

Il doit exister une sorte de document sur ce SDK tiers.

• Quel problème cela résout-il?
• Pourquoi celui-ci a-t-il été choisi?
• Quelles sont les considérations à prendre en compte dans les domaines suivants: versions, mises à niveau, tests, etc.
• Qui prend cette décision?

Vous avez un cas où quelque chose comme ceci a fait son chemin dans le contrôle de version, et vous devriez recommander à tout le monde d'utiliser cette information autant que possible. Seule votre équipe peut décider du lieu où une personne effectuera une recherche dans la documentation, le contrôle de source ou le suivi des bogues pour obtenir le plus d'informations possible sur le sujet. Sinon, vous oublierez que quelqu'un le fera quand même, et vous aurez de la chance si cela rafraîchit la mémoire de quelqu'un et le rétablit rapidement.

L’histoire est un lieu privilégié pour placer des données destinées à un lecteur qui le recherche consciemment et qui a une idée générale de ce qu’il devrait être. C'est un très mauvais endroit pour mettre des données qui doivent être présentées à un utilisateur plutôt que recherchées.

Les histoires sont de très grands corps de texte relativement non trié. Ils sont généralement destinés à fournir aux développeurs des informations détaillées sur les modifications et les raisons de leur modification. Cela peut être une surcharge d'information à moins que l'on sache ce qu'ils recherchent.

Si un utilisateur ne sait pas ce qu'il cherche, les informations sont rapidement enfouies dans des centaines de journaux de validation et ils ne disposent d'aucun outil pour réduire la pile d'informations qui se trouve devant eux.

J'interprète cette situation comme ayant deux problèmes fondamentaux, peut-être trois.

• Une mise à niveau indésirable du SDK a été intégrée à la source, ce qui pourrait nuire au produit.
• D'après la question: le contributeur qui a effectué la mise à niveau indésirable n'était pas au courant d'une décision spécifique antérieure de ne pas effectuer la mise à niveau.

Le premier, à mon avis, est le plus grave. Si une mise à niveau indésirable du SDK peut en faire le code, d'autres problèmes peuvent en faire de même.

Quelqu'un a suggéré d'ajouter un scénario de test d'unité qui échouera s'il détecte la mise à niveau. Bien que cela empêcherait la mise à niveau de se produire, je pense que ceci est une voie dangereuse, menant à un écoulement de lave au fil du temps. Il semble inévitable qu'à l'avenir, le SDK soit mis à niveau pour intégrer de nouvelles fonctionnalités ou des corrections de bugs, ou que l'ancienne version ne soit plus prise en charge. Imaginez les casse-tête, peut-être même les arguments, qui se produiront lorsqu'un tel test unitaire échouera.

Je pense que la solution la plus générale consiste à ajuster le processus de développement. Pour git, utilisez le processus de demande d'extraction . Pour Subversion et les outils plus anciens, utilisez branches et diff. Toutefois, certains processus permettent aux développeurs expérimentés de résoudre ce type de problèmes avant qu’ils ne soient intégrés au code et n’affectent pas les autres développeurs.

Si le processus de demande d'extraction avait été utilisé dans votre situation, et si chaque demande d'extraction était étroite et spécifique, peu de temps aurait été perdu. Une demande d'extraction visant à mettre à niveau le SDK aurait été soumise et refusée avec un commentaire indiquant que la mise à niveau n'est pas souhaitée. Personne d'autre n'aurait été touché, et il ne serait plus nécessaire pour l'instant de revenir sur la mise à niveau du SDK.

Mais pour répondre directement à la question initiale, je suis d'accord avec les autres pour dire que demander à tous les développeurs de lire intégralement l'historique de révision du code, les notes de mise à jour, etc. de tels avis est une perte de temps. Quel est le problème avec un court courrier électronique d'équipe?

Troisième problème possible: pourquoi la mise à niveau n'est-elle pas souhaitée en premier lieu? Clairement, au moins un développeur a pensé que la mise à niveau serait une bonne chose. Il y a beaucoup de bonnes raisons de retarder une mise à niveau, mais aussi beaucoup de mauvaises. Veillez à éviter les coulées de lave (code de compatibilité ascendante inutile) et le culte du fret ("nous ne pouvons pas améliorer cela, mais je ne sais pas pourquoi") anti-patterns!

Je dirais que l'ajout de ce type d'informations à un historique de validation est correct, mais il doit tout de même être documenté correctement. Nous avons récemment commencé à utiliser confluence (par atlassian). Son interrogeable, vous pouvez définir certaines pages comme favoris, etc.

Certains autres outils pourraient être un bloc-notes public dans evernote ou google docs.

En développant la réponse de Karl , je choisirais une approche qui applique automatiquement la restriction dans le cadre du processus d'enregistrement lui-même. Vous avez besoin de quelque chose qui ne nécessite aucune action proactive de la part du développeur, tel que la lecture d'un document / wiki / README, et qui ne peut pas être remplacé secrètement.

Dans le contrôle de source TFS, vous pouvez coder des règles d’archivage personnalisées qui exécutent des règles lors de l’enregistrement. Par exemple, vous pouvez définir une stratégie qui évalue la version d'un fichier de configuration avec un archivage en attente et échouera si elle n'est pas égale à xyz. Ces règles empêchent en fait le développeur d'effectuer l'archivage et peuvent fournir un message descriptif. Les stratégies peuvent être remplacées, mais il est possible de générer des alertes lorsque cela se produit.

Une alternative pourrait être gated-checkins qui échouent avec une forme de test unitaire qui évalue directement ou indirectement la version du SDK, comme l'a mentionné Karl.

J'apprécie que cette réponse soit très centrée sur TFS, mais des fonctionnalités similaires existent peut-être dans les systèmes de contrôle de version / CI qui s'appliquent à votre situation (si ce n'est pas TFS).