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

94

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é?

rjzii
la source
60
Il semble que votre projet pose de très graves problèmes de communication.
Azerbaïdjan
82
Avez-vous besoin de nouvelles recrues pour parcourir l’ensemble de l’enregistrement des commandes?
Steven Evers le
3
Les nouvelles recrues ne devraient pas être en train de parcourir la base de code et de changer les dépendances sans instructions spécifiques.
Midnotion
28
@Midnotion Donc, quelque part sur le chemin de la nouvelle recrue au développeur principal, vous prenez le temps de parcourir l'historique complet des validations? Fascinant.
Nathan Cooper
6
Cela ne fait toujours pas une bonne idée de mettre des informations critiques uniquement dans l'historique de commit.
17 du 26

Réponses:

143

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.

17 sur 26
la source
52
En effet, l'historique des commits est l' historique du projet. Tout comme il serait stupide d'avoir des informations cruciales dans l' historique des modifications du wiki, et non sur la page elle-même. L’historique (code ou wiki) sert de référence à ce qui s’est passé auparavant et non à ce qui devrait se passer maintenant.
Ordous
48
Si possible pour le SDK fictif, j'ajouterais un test unitaire spécialement conçu pour réussir sous V2 et échouer sous V3 avec une déclaration d'assertion explicite donnant la raison de ne pas effectuer de mise à niveau vers V3. L'historique de validation est un bon endroit pour indiquer pourquoi vous apportez cette modification pour les réviseurs de code et non pour documenter les meilleures pratiques.
Klors
3
@Klors Tant que vous ne vous limitez pas aux définitions les plus pédantes des tests unitaires et que vous refusez d'autres types de tests automatisés, un test basé sur la vérification du système de fichiers / etc pour le nom des bibliothèques (si sa version est codée dans celui-ci) ou une somme de contrôle / contrôle du fichier lui-même pourrait être utilisé pour lancer un drapeau rouge à toute personne souhaitant mettre à jour la bibliothèque, même dans les cas où le défaut de la nouvelle version est difficile / impossible à capturer dans un test. (par exemple, conditions de course multithreads)
Dan Neely
18
@ Klors je pensais la même chose, mais à mon avis, le test unitaire devrait démontrer la raison de l'utilisation de v2 sur v3. Ainsi, si le test unitaire réussit avec v4, vous n'avez pas de test unitaire qui requiert v2 pour aucun raison.
Matthieu
9
Une autre raison de ne pas utiliser l'historique de validation pour cela: l'historique de validation est un enregistrement permanent. Si la raison de la non mise à niveau disparaît, l'historique de la validation contiendra toujours l'avertissement de ne pas mettre à niveau, ce qui peut prêter à confusion. Vous avez besoin d'un endroit où des listes d'exigences telles que celle-ci sont mises à jour, de sorte que les développeurs ne soient pas obligés de vérifier si les informations sont toujours pertinentes.
Jules
69

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.

Daenyth
la source
11
Je suis d'accord: le meilleur emplacement pour des informations critiques est "dans autant d'endroits que possible". Peut-être le pom.xmlfichier de projet ou un fichier équivalent, un fichier Lisez-moi, etc., mais l'historique de validation est toujours bon. Si je cherche à mettre à niveau une bibliothèque, je peux consulter l'historique de la version existante pour voir quand elle a été mise à jour, ainsi que toutes les notes sur les problèmes rencontrés par le committer. Mais je ne voudrais pas aller fouiller dans l'histoire pour rassembler toute la documentation. C'est une bonne source supplémentaire .
35

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.

Jeffery Thomas
la source
7
Oui, le commentaire doit être placé "dans le chemin" du changement. Il est donc techniquement impossible de faire l'action sans voir l'avertissement. Cela ressemble beaucoup aux contrôles de sécurité.
dss539
+1 pour la suggestion de créer une histoire / un ticket pour la mise à niveau dans votre outil de suivi des problèmes, définissez sur "En attente" avec une explication de la raison pour laquelle cela ne peut pas encore être fait. Le suivi des problèmes est un endroit que vous pouvez raisonnablement demander aux gens de regarder avant de travailler sur quelque chose.
Andrew Spencer
Citation de Jeff Attwood (bien qu’il parle d’utilisateurs): "La prochaine fois que vous concevez [X], considérez [myopie] [client]. Vous serez peut-être surpris de la myopie de vos [clients]. Pensez longuement à placer les objets directement devant eux, là où ils ne sont pas seulement visibles, mais inévitables. Sinon, ils pourraient ne pas être vus du tout. " blog.codinghorror.com/treating-user-myopia
heltonbiker le
17

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.

Karl Bielefeldt
la source
1
C'est la seule vraie réponse. La capture de l'échec dans un test unitaire empêche la mise à niveau incorrecte de se produire. Période.
Dirk Bester
15

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

Damon
la source
4
+1 Le vrai mot-clé est seulement . Cela n’est certainement pas préjudiciable si l’information est stockée dans un message de validation en plus d’autres endroits plus appropriés. Cela a atteint le PO, car le journal de validation était la seule documentation disponible.
JensG
13

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

pierre précieuse
la source
11

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

FrustratedWithFormsDesigner
la source
4
J'aime l'idée de groupe de messagerie. Trop d’endroits où j’ai travaillé dépendent d’adresses individuelles et les informations ne sont pas transmises aux nouveaux membres.
JeffO
20
Que se passe-t-il si quelqu'un de nouveau vient dans votre équipe? Qui est responsable de leur donner ce genre de connaissance pseudo-institutionnelle?
ABMagil
3
@ABMagil: les informations vont dans un wiki. Les développeurs qui débutent dans l’équipe débutent généralement dans certaines pages d’introduction. Ensuite, ils s'adressent à des personnes spécifiques (qui ont pris le temps d'aider le nouveau développeur) lorsqu'ils ont des questions spécifiques (et ils le font toujours). Pour nous, cela se retrouverait probablement dans le "Guide de configuration du développeur pour ApplicationX", NOTE: Do not use SDK vers. x.y.z because...mais la communication initiale devrait être un courrier électronique.
FrustratedWithFormsDesigner
16
-1 courriels ne fonctionnent pas bien comme documentation
BlueRaja - Danny Pflughoeft
6
@ BlueRaja-DannyPflughoeft: Email fournit une méthode simple et conviviale permettant d'informer immédiatement tous les membres de l'équipe qu'un problème a été découvert lors de l'utilisation d'une version spécifique d'une bibliothèque spécifique et que cette version ne doit pas être utilisée. Comme indiqué, la documentation à long terme est mieux réalisée dans le wiki d'une équipe ou dans un autre type de base de connaissances.
FrustratedWithFormsDesigner
5

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.

JeffO
la source
2

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.

Cort Ammon
la source
cela se lit plus comme un commentaire que comme une réponse. Voir: Comment répondre
moucher le
Bon point, je l'ai développé. Espérons que cela répond mieux aux critères de StackExchange.
Cort Ammon
Je pense que cette réponse répond le mieux au sujet de la question. L'historique de validation est utile pour enregistrer des informations si une personne sait qu'elle devrait rechercher une note. S'il n'y a aucune raison d'examiner le "blâme" d'une ligne donnée, telle que l'inclusion d'un SDK, cette documentation ne sera pas lue.
Seth Battin
1

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!

Wberry
la source
Alors que la mise à niveau du SDK, qui était un numéro de version mineur par opposition à majeur, était ce qui a finalement conduit à cette question, cette ligne de raisonnement fait son apparition dans le groupe depuis un certain temps maintenant.
rjzii
Pourquoi la demande d'attraction aurait-elle été refusée? Comment la personne responsable de cette décision est-elle censée découvrir (ou se souvenir) de la restriction de version?
Ben Voigt
@ BenVoigt Eh bien, soit les responsables de l'équipe étaient au courant de la restriction, soit personne ne s'en souvenait et cela a été redécouvert après avoir rencontré des problèmes. Quoi qu'il en soit, en utilisant les demandes de tirage, il n'y a pas à blâmer le modeste développeur nouvellement embauché, car les aînés approuveraient le changement avant qu'il ne soit autorisé à entrer.
wberry
@wberry: Ou un développeur senior différent a traité la demande d'extraction de celui qui connaissait la restriction de version. À moins que toutes les demandes d'extraction doivent être approuvées par tous les développeurs, cela semble être une dépense de ressources douteuse.
Ben Voigt le
0

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.

JimS
la source
0

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

Pero P.
la source