Faire des changements testés et prêts à relire dans une grande base de code

## Compiler et lancer les tests uniquement via le wrapper du projet Les grands projets encapsulent généralement leur compilateur et leur exécuteur de tests dans une seule commande de projet qui recompile et injecte vos modifications locales avant de lancer quoi que ce soit. Compilez et exécutez toujours via ce wrapper. N'invoquez jamais directement l'exécuteur de tests brut ni un binaire précédemment compilé, car il exécute des artefacts obsolètes qui n'incluent pas votre modification, ce qui rend un résultat positif totalement dénué de valeur probante. Apprenez à identifier les modifications qui peuvent se passer d'une recompilation native. Les changements qui ne touchent que des entrées non compilées, comme les déclarations de types ou les scripts packagés qui se rechargent d'eux-mêmes, ne nécessitent pas de build complet, et en forcer un ne fait que perdre du temps ; exécutez plutôt directement la vérification ciblée, plus légère, pour ce type de cas. Ne mettez pas de délai d'expiration sur un build complet. Un build à froid légitime peut prendre du temps, et l'interrompre produit des échecs confus et trompeurs. Lorsque le wrapper transmet des arguments finaux au programme compilé, placez les options de build avant ces arguments d'exécution afin que le routage reste sans ambiguïté. ## Ajouter les tests au fichier de tests existant du code modifié Par défaut, ajoutez votre test au fichier de test existant pour le code que vous modifiez. Un bug dans le comportement d'une zone du code doit être placé dans le fichier de test existant de cette zone, pas dans un tout nouveau fichier. Garder un test à proximité de la couverture associée le rend facile à trouver et évite de dupliquer la configuration. Reproduisez l'organisation de tests établie du dépôt : tests unitaires regroupés par sous-système, tests de compatibilité, tests de plateforme et d'API web, tests en ligne de commande, et tests d'intégration de bout en bout, chacun dans sa propre zone. Placez votre test là où une couverture équivalente existe déjà. Réservez les dossiers à usage spécifique exactement au cas pour lequel ils sont prévus. Un dossier de régression indexé par un numéro de ticket ne sert qu'à une véritable régression, c'est-à-dire un comportement qui fonctionnait dans une version précédente puis s'est cassé, et cet identifiant doit être réel, jamais un espace réservé. Si le comportement n'a jamais été correct, il ne s'agit pas d'une régression, et le test doit aller dans le fichier ordinaire de ce module. ## Écrire des tests qui donnent le même résultat à chaque exécution Préférez les assertions par snapshot aux vérifications d'égalité fragiles sur des sorties volumineuses, et normalisez le snapshot pour que des valeurs accessoires comme des chemins temporaires ne causent pas de changements inutiles. N'écrivez jamais un test qui vérifie uniquement l'absence d'un plantage ou d'une chaîne d'exception non gérée ; un tel test ne peut jamais échouer dans le pipeline et donne une fausse confiance. Éliminez toute source de non-déterminisme. Ne codez pas en dur un port réseau ; liez-vous à un port éphémère et récupérez celui qui a été attribué. N'utilisez jamais de pause ou de minuteur pour attendre quelque chose, car vous testez une condition, pas l'écoulement du temps ; attendez plutôt la condition réelle. Utilisez l'assistant de répertoire temporaire du harnais de test plutôt que de créer des répertoires temporaires à la main, et évitez les utilitaires shell comme la recherche de fichiers ou de texte à l'intérieur d'un test, en utilisant plutôt les API de fichiers propres au projet. Lorsqu'un test lance un processus, vérifiez sa sortie avant de vérifier son code de sortie, afin qu'un échec produise un message utile plutôt qu'un simple statut non nul. ## Vérifier que les nouveaux tests échouent sans le changement, et ne rapporter que ce qui a été exécuté Un changement n'est pas terminé tant qu'il n'a pas été testé. Si vous n'avez pas exécuté les tests, considérez que le code ne fonctionne pas ; les exécuter fait partie de l'achèvement du travail, ce n'est pas une étape optionnelle. Prouvez que chaque nouveau test sollicite réellement votre changement. Il doit échouer contre la base de référence non modifiée et réussir contre votre build. Un test qui réussit déjà sans votre changement ne prouve rien, donc confirmez les deux directions avant de lui faire confiance. Soyez humble et honnête dans chaque message de commit, réponse de relecture et mise à jour de statut. N'exagérez jamais ce que vous avez accompli ou ce qui fonctionne réellement. Ne rapportez que les résultats que vous avez observés lors de votre propre exécution, et indiquez clairement ce qui reste non vérifié ou inachevé plutôt que de laisser entendre que le travail est terminé. ## Comprendre l'organisation de la base de code avant de la modifier Avant de modifier quoi que ce soit, apprenez comment la base de code est organisée : quelle couche possède quelle responsabilité, où se trouvent les utilitaires partagés, et quels fichiers sont générés par rapport à ceux écrits manuellement. Les fichiers générés sont produits à partir de définitions source, donc modifiez la source et laissez le build les régénérer ; ne modifiez jamais manuellement une sortie générée, car le prochain build l'écrasera. Identifiez le sous-système propriétaire du comportement que vous touchez, qu'il s'agisse de l'analyse syntaxique, de la résolution de modules, des API d'exécution, du réseau, du stockage, du bundler ou du gestionnaire de paquets, afin que votre changement et son test atterrissent tous deux au bon endroit. Suivez le style de code existant. Vérifiez les fichiers voisins pour repérer les motifs établis et alignez-vous dessus plutôt que d'importer les conventions d'un autre projet. Préférez l'idiome propre au langage pour la gestion des ressources, comme le nettoyage automatique basé sur la portée, plutôt qu'un démontage manuel, et respectez les cas particuliers documentés, par exemple des valeurs allouées dans une région qui saute leurs destructeurs lors d'une réinitialisation et qui doivent être libérées explicitement au préalable. ## Lire les règles de relecture et suivre les conventions obligatoires du projet Un projet mature condense dans un ensemble de règles écrites ce sur quoi ses relecteurs bloquent les fusions. Lisez-le avant d'écrire du code qui fait un choix non évident, et lisez tout guide propre au domaine que vous touchez, comme les couches de compatibilité, la conception d'API destinées aux utilisateurs, les chemins critiques sensibles à la performance, le code conditionné par plateforme, les changements de dépendances et de vendoring, ou la documentation et les déclarations de types, avant d'entreprendre ce travail spécifique. Respectez exactement les conventions requises par le projet, car le pipeline automatisé les fait appliquer. Utilisez le préfixe de nom de branche imposé, gardez les commentaires de code courts en déplaçant les explications plus détaillées dans la documentation, écrite uniquement lorsqu'elle est explicitement demandée, et utilisez des chemins absolus dans les opérations sur les fichiers. Lorsque vous faites un changement spécifique à une plateforme, compilez sur chaque cible prise en charge, car le code compilé conditionnellement n'est vérifié en typage que si sa cible correspondante est effectivement construite. ## Utiliser les outils de diagnostic du projet quand la compilation échoue, et les corriger s'ils se trompent Lorsqu'un build automatisé échoue, utilisez les commandes de diagnostic dédiées du projet, celles qui affichent les tests en échec, résument le statut des jobs et enregistrent les logs complets, plutôt que de reconstituer ce tableau à la main. Elles séparent déjà les nouveaux échecs de ceux qui échouent aussi ailleurs et filtrent le bruit habituel. Lorsque vous lisez les retours sur un changement, utilisez la commande qui renvoie le tableau complet. Un listing général omet souvent silencieusement les résumés de relecture et les commentaires au niveau des lignes, donc préférez l'outil qui renvoie ensemble les commentaires de haut niveau, les relectures et les commentaires en ligne, dans une seule vue chronologique et étiquetée. Si la sortie d'un assistant semble incorrecte, comme une annotation mal analysée ou un champ dont la forme en amont a changé, corrigez le présentateur lui-même plutôt que de le contourner en aval. L'assistant n'est qu'une fine couche au-dessus de l'outil sous-jacent, et le réparer garantit que chaque exécution ultérieure reste correcte.