Modifier un monodépôt à plusieurs implémentations sans qu’elles divergent

## Avant de modifier, lire la structure du monodépôt et ses règles locales - Cartographiez le dépôt par produit, langage, domaine fonctionnel, zone d’utilitaires partagés, ensemble de tests, outils de publication et configuration. - Identifiez les répertoires appartenant à chaque implémentation et les règles de premier niveau qui s’appliquent à tout le dépôt. - Avant de modifier une zone imbriquée, lisez son guide local pour agents, son guide de contribution et sa configuration ; les règles locales peuvent préciser la base, mais ne doivent pas l’affaiblir. - Appliquez les règles de compilation, de style et de test propres à un langage uniquement au code écrit dans ce langage. - Repérez la définition de l’espace de travail, les scripts racines et les instructions propres au produit avant de choisir les commandes ou les dépendances. ## Reporter chaque changement visible pour les utilisateurs dans toutes les implémentations - Traitez les implémentations parallèles d’un même produit destiné aux utilisateurs comme des sources de vérité équivalentes. - Lorsque cela est possible, reproduisez chaque changement visible pour les utilisateurs dans toutes les implémentations au sein de la même demande de modification. - Le comportement visible pour les utilisateurs comprend les options, les valeurs par défaut, le traitement de l’environnement, les codes et messages d’erreur, les journaux exploités par des outils, les formats de fichiers et d’états, la disposition du stockage et la sémantique des hooks. - Les restructurations internes, les travaux de performance propres à une implémentation et le nettoyage des tests spécifique à une implémentation n’exigent pas de reproduction artificielle. - Si un travail équivalent ne peut pas être terminé immédiatement, indiquez précisément l’écart de parité, sa raison et ce qui doit être intégré avant que le changement puisse être fusionné. - Ne laissez jamais une implémentation devenir une adaptation dérivée non documentée d’une autre. ## Reconstruire ce que les tests exécutent pour ne pas tester du code obsolète - Installez les dépendances et compilez par le chemin d’initialisation documenté du dépôt avant de faire confiance aux résultats des tests. - Pendant une itération rapide, compilez uniquement le paquet concerné lorsque cela produit le même artefact que celui utilisé par les tests sélectionnés. - Déterminez si les tests de bout en bout exécutent les résultats du code source, les résultats du paquet ou un exécutable regroupé. - Reconstruisez l’ensemble regroupé après toute modification d’un paquet qui le compose lorsque les tests de bout en bout l’utilisent ; sinon, le test risque d’exécuter du code obsolète. - Exécutez la compilation propre au langage approprié pour chaque implémentation modifiée. - Considérez comme preuve non valable un test réussi sur des résultats générés obsolètes. ## Tester seulement ce qui est touché et examiner chaque échec - N’exécutez pas par défaut tout l’ensemble de tests d’un grand dépôt. Commencez par le projet, le fichier ou le cas de test nommé qui est concerné. - Élargissez le périmètre des tests uniquement lorsque les dépendances, les contrats partagés ou les échecs observés le justifient. - Faites correspondre l’environnement d’exécution, l’artefact construit et l’implémentation testée à l’affirmation vérifiée. - Examinez chaque échec au lieu de le qualifier de sans rapport ou de préexistant sans preuve. - Si un échec existait avant le changement, identifiez sa cause et corrigez-le dans le périmètre autorisé ou signalez le blocage concret ; ne l’ignorez jamais silencieusement. - Consignez la commande exacte, la cible concernée et le résultat afin qu’une autre personne contributrice puisse reproduire la preuve. ## Réviser le code modifié : d’abord la sécurité, puis les performances - Suivez le guide de révision du dépôt et limitez les observations au code concerné par le changement et à ses conséquences directes. - Révisez d’abord la sécurité, puis les performances, sauf si une règle de projet plus stricte s’applique. - Pour une observation de sécurité, expliquez l’entrée accessible, la limite de confiance, le chemin d’exploitation et l’impact. - Pour une observation de performance, identifiez le chemin critique, la fréquence, le coût d’allocation ou d’E/S et l’effet probable pour les utilisateurs. - Vérifiez les tests, l’intention de publication et la parité entre les implémentations dans le cadre de l’acceptation. - Ne formulez pas d’observations spéculatives qui ne peuvent pas être reliées au comportement modifié. ## Chercher le code et les dépendances existants avant d’en ajouter - Recherchez dans les paquets partagés, les fonctions auxiliaires du système de fichiers, les utilitaires cryptographiques, les utilitaires de texte et les modules de domaine voisins avant d’implémenter une logique non triviale. - Réutilisez un utilitaire exporté existant lorsqu’il possède déjà le comportement requis. - Si une logique similaire est confinée dans un paquet, extrayez le contrat commun vers l’emplacement partagé approprié le plus précis au lieu de la copier. - Pour une fonction courante, préférez une dépendance existante et maintenue lorsqu’elle convient, qu’elle est suffisamment légère et qu’elle est autorisée par la politique du dépôt. - Ajoutez une nouvelle dépendance au paquet le plus précis qui en a besoin ; ne la remontez que lorsque plusieurs paquets la partagent réellement. - N’ajoutez pas d’enveloppes qui se contentent de renommer ou de transmettre une opération existante sans ajouter de contrat. ## Suivre les règles des messages de commit sans contourner les hooks - Utilisez la convention obligatoire du dépôt pour les messages de commit et choisissez le type de changement qui reflète l’impact pour les utilisateurs. - Avant un commit, vérifiez que les hooks du dépôt sont installés et actifs ; une nouvelle copie de travail peut ne pas les avoir enregistrés. - Ne contournez jamais un contrôle de commit en échec, ne désactivez pas le hook et n’ajoutez pas de fichier de suppression. Corrigez le message ou le changement sous-jacent. - Évitez les références numériques non qualifiées aux incidents, car la plateforme d’hébergement peut les relier au mauvais dépôt ; utilisez une référence qualifiée par le dépôt ou une URL absolue. - Placez les identifiants de code ressemblant à des noms d’utilisateur dans du code en ligne ou retirez les mentions inutiles afin qu’un commit ne prévienne pas des personnes sans rapport. - Utilisez une numérotation de liste sans marqueur de référence lorsque vous énumérez des éléments. ## Ajouter une entrée de publication quand un paquet publié change - Ajoutez une entrée d’intention de publication chaque fois qu’un changement concerne un paquet publié. - Nommez tous les paquets concernés et choisissez l’impact sur la version parmi une correction de défaut, une fonction rétrocompatible ou un changement incompatible. - Rédigez l’entrée pour les utilisateurs et restez concis ; placez la justification de l’implémentation dans le message de commit. - Incluez le paquet principal de ligne de commande pour les changements apportés à son implémentation principale lorsque la politique du dépôt l’exige. - Pour les changements propres à une implémentation, ne nommez que les produits réellement modifiés. Un changement de parité doit nommer les paquets de chaque implémentation concernée. - Respectez les voies de publication stable et préliminaire, les groupes de versions fixes et la procédure de promotion du dépôt. ## Ne commenter que les raisons que le code ne montre pas lui-même - Préférez des noms, des types, des limites de fonctions auxiliaires et un flux de contrôle qui permettent au code de s’expliquer lui-même. - N’ajoutez pas de commentaires qui répètent une opération, dupliquent la documentation de la fonction appelée ou décrivent une syntaxe évidente. - Documentez une raison partagée une seule fois auprès du responsable commun au lieu de la répéter à chaque point d’appel. - Utilisez des commentaires de documentation pour les préconditions, les postconditions, les cas limites et les garanties non évidentes. - Conservez l’historique des restructurations et les descriptions de conceptions retirées dans l’historique du contrôle de versions et les messages de changement, et non dans les commentaires actuels du code source. - Avant d’ajouter du texte explicatif, demandez-vous si renommer, restructurer ou extraire communiquerait l’idée plus sûrement. ## Suivre les règles de formatage et de gestion des erreurs du dépôt - Utilisez l’outil de mise en forme et le guide de style propre au langage du dépôt ; conservez le regroupement et l’ordre établis des importations. - Préférez les fonctions aux classes avec état lorsque le code existant le fait et remplacez les longues listes de paramètres par un objet d’options typé. - Utilisez des types d’erreur de domaine stables pour les échecs accessibles aux utilisateurs, conservez les codes d’erreur, incluez le contexte pertinent et ne masquez jamais les erreurs inattendues. - Interceptez uniquement la condition d’erreur attendue et utilisez une vérification d’erreur native sûre entre contextes dans les environnements de test virtualisés. - Donnez des noms verbaux aux fonctions, maintenez une terminologie cohérente et renommez un concept partout lorsque son contrat change. - Préférez les opérations simples sur les chaînes pour les analyses simples et l’analyseur structuré existant pour les grammaires qui exigent un retour en arrière. - Faites passer les valeurs configurables par la couche de configuration, gardez les gestionnaires de commandes indépendants de la présentation et évitez les politiques codées directement. - Utilisez des E/S asynchrones, exécutez les opérations indépendantes en parallèle, attendez les terminaisons requises et sortez des boucles le travail invariant. ## Garder la demande de modification fidèle aux changements réels jusqu’à la fusion - Ouvrez une demande de modification avec le modèle du dépôt, conservez les sections obligatoires et retirez uniquement le contenu que le modèle indique comme facultatif. - Maintenez son titre et sa description synchronisés avec les changements réels après chaque mise à jour importante. - Répondez aux conversations de révision traitées avec la solution et la révision qui l’étaye, puis marquez la conversation comme résolue. - Étiquetez le contenu distant créé par des agents conformément à la politique du dépôt sans exposer de contexte d’implémentation sensible. - Utilisez le processus de résolution des conflits approuvé par le dépôt afin que la base reste actuelle, que les données de verrouillage générées soient reconstruites de façon déterministe et que la possibilité de fusion soit vérifiée. - Examinez manuellement les conflits dans les contenus non générés. Toute mise à jour forcée ou autre réécriture distante de l’historique exige une autorisation explicite et une cible vérifiée.