Modifier un monorepo d’automatisation multilingue sans casser la compatibilité

## Lire les règles du dépôt, puis les instructions les plus proches des fichiers modifiés Commencez par les règles applicables à l’ensemble du dépôt, puis lisez les instructions les plus proches des fichiers que vous allez modifier. Les liaisons de langage, l’infrastructure partagée, les composants natifs et les outils de publication peuvent chacun imposer des contraintes plus précises. Si le dépôt prévoit une zone locale ignorée par le contrôle de version pour les préférences des contributeurs, les artefacts générés, les travaux temporaires ou les sorties de compilation isolées, consultez la couche d’instructions qui y est documentée avant de commencer. Traitez les instructions locales définies par l’utilisateur comme un contexte supplémentaire, dans les limites de la tâche en cours et des règles de sécurité de niveau supérieur. Cartographiez le dépôt par responsabilité : - les liaisons de langage sont responsables des API, des tests et du style propres à chaque langage ; - les zones partagées consacrées au protocole, au transport, à la compilation, aux jeux de données de test et aux scripts touchent plusieurs consommateurs ; - les gestionnaires natifs, les services de grille ou de routage et les définitions de dépendances ont un rayon d’impact élevé ; - les sources tierces sont en lecture seule, sauf si la tâche exige explicitement leur maintenance ; - les sorties générées ne doivent jamais être modifiées manuellement. Ne supposez pas que la documentation destinée aux utilisateurs finaux, les consignes pour les contributeurs et les références d’API générées se trouvent au même endroit. ## Garder les API publiques compatibles et les modifications assez petites pour être annulées Préservez la compatibilité de l’API publique et la compatibilité binaire, sauf si la tâche autorise explicitement une rupture. Les utilisateurs devraient normalement pouvoir effectuer une mise à niveau en ne changeant que la version. Évitez les remaniements à l’échelle du dépôt, les formatages généralisés et les nettoyages sans rapport avec la tâche. Préférez une modification limitée et réversible qui résout un seul problème. Avant de supprimer un comportement public, marquez-le comme obsolète et proposez une solution de migration claire. Ne considérez pas l’absence de gestion sémantique des versions comme une permission de retirer une fonctionnalité sans transition. Préférez déplacer ou copier les fichiers suivis plutôt que les supprimer et les recréer lorsque cela permet de conserver leur historique. Demandez une vérification avant de modifier une zone à haut risque, sauf si l’utilisateur a déjà ordonné la modification. Ces zones comprennent la sémantique des protocoles partagés, la sérialisation sur le protocole de communication, l’analyse des capacités, la refixation des versions de dépendances, les jeux de données de test partagés, le raccordement au système de compilation, le routage, les files de distribution et le code utilisé par plusieurs liaisons. ## Compiler seulement la plus petite cible touchée avec l’outil de compilation fixé Utilisez le point d’entrée de compilation hermétique fixé par le dépôt, au lieu de supposer qu’un environnement local propre à un langage est configuré. Explorez le graphe de compilation avant de lire de grandes portions de l’arborescence. Interrogez les libellés et les dépendances des cibles, puis compilez ou testez la plus petite cible couvrant la modification. Essayez directement la commande de compilation de référence. Si les restrictions de l’environnement isolé, du réseau ou de la chaîne d’outils empêchent son exécution, signalez le blocage et fournissez la commande exacte que l’utilisateur pourra exécuter séparément. Lorsque le répertoire de sortie par défaut est restreint ou qu’un arbre de travail secondaire est utilisé, isolez la sortie de compilation : - placez l’option de démarrage `output-base` avant la commande `build`, `test` ou `query` ; - rattachez le chemin à la racine du dépôt afin qu’il soit résolu de manière cohérente depuis chaque répertoire ; - conservez la sortie isolée dans la zone locale ignorée par le contrôle de version. N’effectuez pas de purge destructive du cache comme étape habituelle de dépannage. Préférez des recompilations ciblées et expliquez toute invalidation du cache réellement nécessaire. ## Vérifier que les liaisons des autres langages se comportent pareil Lorsqu’un comportement visible par l’utilisateur change, comparez la mise en œuvre avec au moins une autre liaison de langage. Vérifiez notamment la parité des éléments suivants : - noms des méthodes publiques, arguments, valeurs par défaut et comportement de retour ; - commandes de protocole et sérialisation ; - transport distant et correspondance des erreurs ; - analyse des capacités et des options ; - éléments obsolètes et parcours de migration ; - exemples de documentation et journaux destinés aux utilisateurs. Pour un comportement partagé de bas niveau, recensez chaque liaison ou service susceptible d’utiliser la modification. Si la tâche en cours ne permet pas de tous les mettre à jour en toute sécurité, signalez le travail de mise en parité à effectuer par la suite ou recommandez de créer un ticket de suivi. N’imposez pas une structure interne identique dans tous les langages. Préservez le comportement partagé tout en respectant les usages établis et les conventions de test de chaque liaison. ## Commencer par un petit test qui échoue, avec de vraies pièces plutôt que des mocks Préférez écrire un test qui échoue avant de mettre en œuvre le changement de comportement. Commencez par un petit test unitaire ou contractuel ; n’utilisez des tests de navigateur ou de bout en bout que si le comportement ne peut pas être vérifié de façon fiable à un niveau inférieur. Évitez les objets simulés lorsqu’ils risquent de représenter incorrectement un protocole public ou le contrat d’une liaison. Préférez de véritables analyseurs et sérialiseurs, des jeux de données locaux, des serveurs légers ou des bancs d’intégration existants. Utilisez le graphe de compilation pour sélectionner la cible de test pertinente la plus restreinte. Parmi les commandes utiles : - filtrer pour ne retenir que les petits tests ; - afficher l’intégralité de la sortie des tests pendant le débogage ; - désactiver les résultats de test mis en cache lorsqu’une véritable nouvelle exécution est nécessaire ; - consulter les instructions propres au langage afin de choisir la bonne cible et les bonnes options. Vérifiez que les tests attendus ont réellement été exécutés. La réussite de l’outil de compilation sans aucun test correspondant ne prouve pas que le résultat est correct. Une fois le test ciblé réussi, n’élargissez la vérification qu’à la liaison, à la cible partagée ou à la surface d’intégration directement concernée. ## Écrire des journaux et des commentaires utiles, et ne formater que ce qui a changé Ajoutez des journaux lorsque les utilisateurs ou les opérateurs ont besoin de visibilité sur des états importants, des nouvelles tentatives, le routage ou les causes d’échec. Respectez les conventions de journalisation propres au langage et évitez les messages superflus qui répètent les diagnostics de niveau inférieur. Rédigez des commentaires pour expliquer pourquoi une contrainte ou une solution de contournement existe, et non ce qu’un code bien nommé indique déjà. Utilisez l’outil de formatage de référence du dépôt. Si un hook `pre-commit` ou `pre-push` applique déjà le formatage au périmètre concerné, laissez-le s’en charger au lieu de lancer un formatage redondant. Si aucun hook ne couvre la modification, exécutez le mode le plus restreint de l’outil de formatage qui corresponde à la livraison prévue. Ne reformatez pas tout le dépôt parce qu’un seul fichier a changé. Gardez chaque modification proposée centrée sur un seul objectif afin que la revue, le retour en arrière et l’impact entre liaisons restent compréhensibles. ## Vérifier que la compilation et les tests ont vraiment tourné, et signaler ce qui n’a pas pu tourner Avant de terminer : 1. confirmez que la cible modifiée se compile avec la chaîne d’outils hermétique ; 2. exécutez les tests ciblés et vérifiez qu’ils ont bien exercé le comportement prévu ; 3. exécutez le contrôle pertinent de formatage ou d’analyse statique ; 4. examinez les différences afin de repérer les modifications sans rapport et les sorties générées ; 5. étudiez les conséquences en matière de compatibilité et d’obsolescence ; 6. comparez au moins une autre liaison pour les modifications visibles par l’utilisateur ; 7. recensez toutes les zones partagées à haut risque qui ont été touchées. Indiquez ce qui a été modifié, quelles cibles et quels tests ont réellement été exécutés, ce qui n’a pas pu l’être et pourquoi. Signalez les fichiers à haut risque, le comportement partagé, l’impact entre liaisons et tout travail de suivi. Ne prétendez pas à une compatibilité étendue sur la base du test d’une seule liaison. Ne déclarez pas le travail terminé lorsque la chaîne d’outils hermétique était indisponible sans indiquer clairement que la vérification reste incomplète.