L'historique de validation doit-il être utilisé pour transmettre des informations critiques aux développeurs?
Lors d'une réunion concernant la restauration d'un SDK tiers de la dernière version, il a été noté que nos développeurs avaient déjà signalé dans l'historique de validation que la dernière version ne devait pas être utilisée.
Certains développeurs ont fait valoir qu'il s'agissait d'une mauvaise pratique et qu'elle aurait plutôt dû être notée dans le fichier source (c'est-à-dire // Don't upgrade SDK Version x.y.z, see ticket 1234) ou dans un fichier de projet README. D'autres ont fait valoir que, puisque l'historique des validations fait partie de la documentation du projet, il s'agit d'un emplacement acceptable pour ces informations, car nous devrions tous les lire de toute façon.
L'historique de validation doit-il être utilisé pour transmettre des informations critiques à d'autres développeurs ou ces informations doivent-elles être dupliquées vers un autre emplacement tel qu'un projet README ou des commentaires dans le fichier source pertinent?
Si j'allais envisager la mise à niveau vers une version plus récente d'un SDK tiers, le dernier endroit que je rechercherais serait dans le historique du système de contrôle de 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'ils devraient regarder en arrière dans le temps dans votre système de contrôle de code source pour découvrir que ce n'est pas une bonne idée.
Ici, nous avons un wiki d'équipe qui a une poignée de pages avec des informations intéressantes que chaque développeur lit (conventions de codage, comment configurer un environnement de développement pour construire le produit, quels trucs tiers vous devez installer, etc.). C'est le genre d'endroit qui serait approprié pour un avertissement contre la mise à niveau d'une bibliothèque tierce.
Il doit être noté dans l'historique de validation, mais le meilleur endroit absolu pour placer l'avis est au même endroit où 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 problème # 123 comprendrait des détails sur la façon dont il se bloque, la version que vous avez mise à jour qui a provoqué les plantages, et il devrait probablement être ajouté à nouveau à votre backlog pour être revu plus tard - il est possible qu'il existe une nouvelle version plus récente qui résout le problème. Soit automatiquement en modifiant le ticket, soit manuellement vous-même, il enverra un e-mail à l'équipe pour lui faire connaître le problème actuel maintenant, et en étant dans le tracker, il permettra aux gens de le retrouver plus tard.
La raison de le mettre avec la déclaration de dépendance est que quiconque veut changer la version le verra au moment où il veut le changer et comprendra pourquoi il ne devrait pas le faire.
Je ne commenterais pas dans le code source car je peux facilement imaginer une situation où quelqu'un vérifie vos dépendances et commence à les mettre à niveau. Ils ne devraient pas avoir besoin de parcourir la base de code pour chaque commentaire TODO pour ce faire.
La liaison avec le ticket de problème permet à un développeur curieux de savoir comment il a échoué et de le réexaminer ultérieurement. Sans cela, il pourrait devenir assez statique et ne plus jamais être mis à jour.
Les informations cruciales et non intuitives doivent être documentées à l'endroit où les gens regarderont lors de l'examen des informations.
Pour les équipes et les projets sur lesquels j'ai travaillé, je validerais la restauration avec le commentaire expliquant pourquoi la nouvelle version a échoué. J'ajouterais une histoire de backlog pour réessayer la mise à niveau si la nouvelle version est corrigée. J'ajouterais des commentaires au système de build/scripts de build où la bibliothèque est liée.
Le retour en arrière fournira aux futurs développeurs un contexte lorsqu'ils examineront l'historique du projet. L'historique du carnet de commandes conserve le besoin de cette mise à niveau en tant que partie active du projet. Les commentaires du système de build sont là où les changements devront être lorsque la bibliothèque sera enfin mise à jour.
Je ne le commenterais pas dans le code et je ne l'ajouterais pas à un fichier README. Les développeurs qui envisagent d'essayer la mise à niveau ne regarderont pas ces éléments. Si vous l'ajoutez là-bas, lorsque le problème avec la bibliothèque sera finalement résolu et qu'une mise à niveau sera effectuée, vous devrez le supprimer. Cette étape est souvent oubliée: aboutir à des notes contre-productives au projet.
Si votre projet a une configuration 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 verra lors 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, et lorsque le moment sera venu, le développeur le verra et supprimera la note afin de ne pas confondre les futurs développeurs.
Je voulais donner le commentaire de Matthew plus d'attention en soulignant son idée importante dans une réponse. Il y a une raison pour laquelle vous ne voulez pas mettre à niveau votre SDK, et cette raison devrait être capturée dans un test unitaire. Pas une vérification pour un numéro de révision, mais la véritable raison sous-jacente.
Par exemple, disons qu'il y a un bug dans la nouvelle version. Écrivez un test unitaire qui vérifie ce bogue. S'ils corrigent ultérieurement ce bogue dans le SDK, la mise à niveau se fera sans problème. S'il y a un changement d'API incompatible, écrivez un test qui vérifie que votre code prend en charge la nouvelle API ou que le SDK prend en charge l'ancienne API. C'est plus un test d'intégration qu'un test unitaire, mais cela devrait toujours être faisable.
Mon entreprise génère plus de 50 commits par jour, et nous ne sommes pas vraiment énormes. Même si chaque développeur lit chaque message de commit, ce qui n'est pas le cas, la raison pour laquelle nous avons besoin d'un historique de commit enregistré est que les gens ne s'en souviennent pas. Et les gens ne reviennent pas et ne lisent pas l'histoire plus tard, sauf en cas de problème. Et ils n'ont aucune raison de soupçonner un problème sur une mise à niveau qui, à leur connaissance, ne s'est pas encore produit.
En tout cas, envoyez un e-mail pour éviter la duplication du travail à court terme, et notez-le dans vos scripts de construction et un README ou errata. Cependant, surtout si le problème avec la nouvelle version est subtil et de temps pour dépanner, vous avez besoin d'un moyen de le rendre évident. Cela signifie un test unitaire.
Je reformule la question comme suit: "Dois-je communiquer les 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. J'essaie beaucoup de communiquer (c'est quelque chose dans lequel la plupart des équipes de développement, selon mon expérience, doivent faire des efforts actifs) et je fais certainement tout ce que je peux 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 ferais en sorte que les personnes qui devraient le savoir aient de la visibilité), je le mentionnerais probablement face à face (en espérant pour laisser au moins quelqu'un avec un certain sentiment persistant que "Gee, je pense que Damon a dit quelque chose à propos de la mise à jour"), et je laisserais bien sûr un commentaire dans le code au moment où le SDK a été inclus afin que personne ne puisse mettre à jour sans avoir la chance de le voir. Je pourrais peut-être voir si je pourrais le brancher quelque part sur notre wiki de développement, bien que cela se fasse davantage en tenant compte des futures embauches, pas de 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 ne déciderais certainement pas que l'un des éléments les moins utilisés et à faible signal de notre documentation et en rester là.
Cela devrait être dans l'historique des validations, mais pas seulement dans l'historique des validations, imaginez un instant que vous embauchez un nouveau développeur. Vous attendez-vous à ce que le nouveau développeur lise chaque message de validation au cours des 10 dernières années de votre projet, car certains d'entre eux seront essentiels à la compréhension de votre base de code?
Deuxièmement, dites que la situation mais pas les modifications de code, allez-vous effectuer des validations de "documentation" afin que vous puissiez ajouter des messages de validation dans le sens de "le message de validation de la révision 5432 est maintenant incorrect, voici la situation actuelle."
Je ne sais pas comment votre équipe communique, mais je pense que le moyen le plus efficace de le dire est de premier envoyer et envoyer un e-mail au groupe de messagerie de l'équipe, marqué comme "URGENT" avec le corps disant
Les gars, nous ne pouvons pas utiliser le SDK v x.y.z car il provoque le débordement du tampon Foo et le service Bar se bloque. Restez avec la version x.y.y
C'est ce que nous avons fait ici et c'est le moyen le plus fiable de diffuser le message. Si vous vraiment voulez être pointilleux (et si votre système de messagerie le permet), demandez une "confirmation de lecture" sur l'e-mail.
Une fois que vous en avez parlé à toute l'équipe, une documentation plus détaillée doit être mise dans un wiki d'équipe. Cela variera selon la façon dont vous structurez votre documentation. Si vous avez une section spécifiquement pour vos dépendances et exigences d'applications, ce serait un bon endroit pour l'ajouter.
Un autre endroit pour documenter ce type de problème peut ê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 code source peut être très long et, selon les développeurs, peut avoir plusieurs entrées par jour. Quelqu'un qui est parti en vacances pendant une semaine pourrait ne pas avoir le temps de lire la valeur d'une semaine de l'historique des validations. Le fichier README est un meilleur endroit car il est un peu plus central et les gens pourraient être plus enclins à le lire, mais vous ne pouvez pas vous assurer que tout le monde --- lire le README. Eh bien, je suppose qu'ils pourrait s'ils voient que cela a été changé ...
Quelque chose comme ça aurait dû être mis dans les commentaires de validation, mais cela bénéficiera également d'être ailleurs.
Celui qui prend la décision de mettre à niveau, doit avoir les faits. Cette personne peut ne pas vivre sous contrôle de source. Et si quelqu'un avait lu ce problème sur SO et ne l'avait jamais mis dans la base de code?
Il doit y avoir une sorte de document sur ce SDK tiers.
- Quel problème résout-il?
- Pourquoi a-t-on choisi celui-ci en particulier?
- Quelles considérations doivent être prises en ce qui concerne: les versions, les mises à niveau, les tests, etc.
- Qui prend cette décision?
Vous avez un cas où quelque chose comme ça a fait son chemin dans le contrôle de version, et vous devriez recommander à tout le monde d'utiliser ces informations autant que possible. Seule votre équipe peut décider où quelqu'un va effectuer une recherche dans la documentation, le contrôle des sources ou le traqueur de bogues pour obtenir autant d'informations que possible sur le sujet. Sinon, vous oublierez, quelqu'un le fera de toute façon, et vous aurez de la chance s'il rafraîchit la mémoire de quelqu'un et le fait rapidement revenir en arrière.
L'histoire est un excellent endroit pour mettre des données destinées à un lecteur qui les recherche consciemment et qui a une idée générale de l'endroit où elles devraient se trouver. 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és. Ils sont généralement destinés à fournir au développeur des informations détaillées sur ce qui a changé et pourquoi il a été modifié. Cela peut être une surcharge d'informations à moins que l'on sache ce qu'ils recherchent.
Si un utilisateur ne sait pas ce qu'il recherche, les informations sont rapidement enfouies sous des centaines de journaux de validation et ils n'ont aucun outil pour réduire la pile d'informations devant eux.
J'interprète cette situation comme ayant deux problèmes fondamentaux, peut-être trois.
- Une mise à niveau indésirable du SDK en a fait la source, où elle pourrait affecter négativement le produit.
- De la question: le contributeur qui a effectué la mise à niveau indésirable ne connaissait pas une décision précédente et spécifique de ne pas mettre à niveau.
Le premier d'entre eux, à mon avis, est le plus grave. Si une mise à niveau indésirable du SDK peut en faire partie du code, il en va de même pour d'autres problèmes.
Quelqu'un a suggéré d'ajouter un scénario de test unitaire qui échouera s'il détecte la mise à niveau. Bien que cela empêcherait la mise à niveau de se produire, je pense que c'est un chemin dangereux, conduisant à coulée de lave au fil du temps. Il semble inévitable qu'à un moment donné à l'avenir, le SDK soit mis à niveau, pour apporter de nouvelles fonctionnalités ou corrections de bogues, ou parce que l'ancienne version n'est plus prise en charge. Imaginez le grattage de tête, peut-être même des arguments, qui se produira lorsqu'un tel test unitaire échoue.
Je pense que la solution la plus générale est d'ajuster le processus de développement. Pour git, utilisez le processus pull request . Pour Subversion et les outils plus anciens, utilisez branches et diff. Mais ont un processus certains qui permet aux développeurs seniors d'attraper ce genre de problèmes avant ils arrivent dans la base de code et affectent 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, il n'y aurait pas eu beaucoup de temps perdu. Une demande d'extraction pour mettre à niveau le SDK aurait été soumise et refusée avec le commentaire que la mise à niveau n'est pas souhaitée. Personne d'autre n'aurait été touché et il ne serait plus nécessaire de revenir sur la mise à niveau du SDK.
Mais pour répondre directement à la question d'origine, je suis d'accord avec les autres qui attendent de tous les développeurs qu'ils lisent l'intégralité de l'historique des révisions du code, des notes de publication, etc. pour des avis comme celui-ci est une perte de temps précieux. Quel est le problème avec un court e-mail d'équipe?
Troisième problème possible: pourquoi la mise à niveau n'est-elle pas souhaitée en premier lieu? De toute évidence, au moins un développeur a pensé que la mise à niveau serait une bonne chose. Il existe de nombreuses bonnes raisons de retarder une mise à niveau, mais aussi de nombreuses mauvaises. Prenez soin d'éviter la coulée de lave (code de rétrocompatibilité inutile) et culte du fret ("nous ne pouvons pas mettre à jour cela, mais je ne sais pas pourquoi") anti-modèles!
Je dirais que l'ajout de ce type d'informations à un historique de validation est correct, mais il doit toujours être documenté correctement. Nous avons récemment commencé à utiliser la confluence (par atlassian). Il est consultable, vous pouvez définir certaines pages comme favoris, etc.
Certains autres outils peuvent être un cahier public dans evernote ou google docs.
S'étendant sur réponse de Karl , j'opterais pour 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, comme la lecture d'un doc/wiki/README, et ne peut pas être ignoré secrètement.
Dans la zone de contrôle de source TFS, vous pouvez coder personnalisé politiques de consignation qui exécutent les règles de consignation. Par exemple, vous pouvez définir une stratégie qui évalue la version dans un fichier de configuration avec un archivage en attente et échouera si elle n'est pas égale à x.y.z. Ces règles empêchent en réalité 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 des enregistrements bloqués qui échoueront avec une certaine forme de test unitaire qui évalue directement ou indirectement la version du SDK, comme Karl l'a mentionné.
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 (sinon TFS).