Modifier un grand monodépôt Python de flux de travail sans le casser

## Trouver le paquet responsable et ses instructions avant de modifier Dans le texte courant, utilisez la terminologie de domaine de référence du projet. Conservez les identifiants littéraux, commandes, chemins, clés de configuration et noms de compatibilité exactement comme le code l’exige ; ne les reformulez pas uniquement pour harmoniser le style. Avant toute modification : - Identifiez le paquet responsable, ses instructions locales et le guide d’architecture ou de test le plus proche. - Utilisez le lanceur de développement et de test géré par le projet au lieu d’appeler directement les outils du système hôte. - Installez les points d’accroche ou les adaptateurs de commandes du dépôt au moyen de sa procédure documentée de configuration initiale à effectuer une seule fois. - Placez les scripts auxiliaires temporaires uniquement dans la zone de développement montée prévue à cet effet et retirez-les une fois la tâche terminée. - Choisissez les vérifications en fonction des fichiers et des paquets réellement modifiés. Considérez les fichiers de verrouillage de dépendances générés et les artefacts similaires comme les sorties d’un générateur officiel, jamais comme du code source à modifier manuellement. ## Empêcher l’ordonnanceur d’exécuter le code des flux et les processus d’exécution d’accéder directement à la base de données Comprenez le flux de données avant de modifier le code d’orchestration : 1. Les auteurs définissent les flux de travail au moyen du SDK public. 2. Des processus isolés analysent ces définitions et enregistrent durablement les données sérialisées des flux de travail. 3. Les ordonnanceurs lisent les données sérialisées et ne doivent pas exécuter le code de flux de travail fourni par les auteurs. 4. Les processus d’exécution accomplissent les tâches au moyen du SDK ou de l’API pris en charge et ne doivent pas accéder directement à la base de données de métadonnées. 5. Les services d’API servent d’intermédiaires entre l’état persistant et les interactions de l’interface utilisateur et des clients. 6. Les services de déclenchement d’événements fonctionnent séparément des ordonnanceurs et des processus d’exécution. Utilisez entre les composants des identifiants d’accès de courte durée et de portée strictement limitée. Les contrôles logiciels qui découragent l’accès direct à la base de données constituent des garde-fous utiles, mais pas une frontière de sécurité face à du code délibérément malveillant. Classez tout problème de sécurité présumé avant de proposer une correction : - Une violation exploitable du modèle de confiance documenté constitue une vulnérabilité. - Un comportement déjà déclaré hors du modèle de confiance constitue une limitation connue. - Une option de déploiement plus sûre qui ne répare pas une garantie violée constitue une recommandation de durcissement. Maintenez ces catégories distinctes afin que la gravité et la mesure corrective correspondent au risque réel. ## Placer chaque dépendance dans le paquet qui l’importe Considérez le monodépôt comme un ensemble de distributions connexes plutôt que comme un paquet unique et indifférencié. L’orchestration centrale, les SDK publics, les intégrations de fournisseurs, les outils en ligne de commande, les modèles de déploiement, l’outillage de développement et les scripts peuvent suivre des cycles de publication et des règles de dépendances différents. Pour une bibliothèque partagée : - Gardez son API restreinte et indépendante. - Donnez-lui sa propre arborescence de sources, ses propres tests, sa propre configuration et ses dépendances déclarées. - Utilisez les liens d’espace de travail pris en charge par le dépôt au lieu de dupliquer le code. - Testez la bibliothèque elle-même et chaque composant consommateur directement concerné. Placez chaque dépendance dans la distribution qui l’importe. Lorsqu’une modification franchit les limites des paquets, vérifiez la direction des importations et la responsabilité de publication avant de modifier les manifestes. Régénérez les fichiers de verrouillage avec la procédure prise en charge et examinez l’écart de dépendances obtenu afin de repérer les changements sans rapport. ## Écrire du code Python clair et garder chaque modification petite Formatez et analysez statiquement chaque fichier Python modifié tant que la modification reste limitée. Gardez le comportement en production explicite : - N’utilisez pas d’assertions pour la validation à l’exécution ni pour la gestion d’erreurs récupérables. - Rédigez des commentaires qui expliquent les contraintes ou l’intention, sans raconter le code. - Mesurez les durées avec une horloge monotone. - Conservez les importations au niveau du module, sauf dans les cas documentés de dépendances circulaires, de chargement différé ou de dépendances facultatives. - Protégez les importations coûteuses utilisées uniquement pour la vérification des types afin qu’elles n’affectent pas le démarrage du programme. - Levez l’exception pertinente la plus précise ; n’introduisez pas d’exception de base générique qui intercepterait tout. - Convertissez les défaillances du domaine en réponses propres au protocole uniquement à la frontière de transport. - Nommez les fonctions avec des verbes d’action et conservez l’en-tête de licence requis. Préférez une modification limitée et facile à examiner à une refactorisation opportuniste. Si un nettoyage n’est pas nécessaire au comportement demandé, réservez-le à une modification distincte. ## Écrire dans la base de données par petits lots pour ne pas ralentir l’ordonnanceur Les fonctions qui reçoivent une session de base de données ne doivent pas valider implicitement la transaction. Faites de la session un paramètre obligatoirement nommé lorsque la base de code suit cette convention, et laissez le responsable de la transaction décider quand la valider ou l’annuler. Évitez les écritures massives sans limite dans les boucles de l’ordonnanceur ou de maintenance : 1. Filtrez selon des colonnes indexées. 2. Traitez un lot de taille limitée. 3. Validez ou libérez la transaction entre les lots. 4. Continuez jusqu’à ce qu’il ne reste aucune ligne admissible. Cela limite la durée des verrouillages, la croissance de la mémoire et la privation de ressources des autres tâches de l’ordonnanceur. Confirmez le comportement sur la base de données par défaut et exécutez des tests de couverture avec un autre moteur de base de données lorsque la requête modifiée dépend d’une sémantique propre au moteur. Ne considérez jamais une commande de nettoyage destructif comme une procédure ordinaire de dépannage. Déterminez la cible exacte et obtenez l’autorisation requise avant de supprimer des bases de données, des volumes, des mémoires cache ou des données utilisateur. ## Écrire d’abord un test qui échoue, puis élargir les tests seulement si besoin Commencez par un test qui décrit exactement le comportement à modifier et confirmez qu’il échoue sans la mise en œuvre. Apportez ensuite la plus petite modification qui permet au test de réussir. Utilisez l’environnement de test et les outils auxiliaires privilégiés par le dépôt : - Reproduisez l’organisation des sources dans l’arborescence de tests. - Utilisez des substituts de test liés à la spécification afin que toute dérive de l’interface provoque un échec manifeste. - Utilisez les mécanismes pris en charge pour remplacer la configuration et contrôler le temps. - Paramétrez les variantes pertinentes d’entrées et de moteurs de base de données. - Marquez précisément les tests de base de données et gardez les autres tests indépendants de la configuration de la base. - Vérifiez les noms et les champs structurés des événements plutôt que le texte instable des journaux après rendu. Ne testez pas isolément la bibliothèque standard ni une dépendance tierce. Testez le comportement d’intégration dont ce code est responsable. Exécutez d’abord un test ciblé, puis la suite de tests du paquet concerné, la vérification statique des types et l’analyse statique ; n’exécutez des suites plus larges que si l’étendue des dépendances le justifie. ## Modifier ensemble les règles de CI et la documentation, avec des notes de version seulement pour les changements visibles Lorsque le comportement sélectif de l’intégration continue change, mettez à jour ensemble la logique de sélection, ses tests et sa documentation. Une règle qui n’existe que dans le code ou que dans le texte est incomplète. Ajoutez des métadonnées de publication uniquement pour les modifications visibles par l’utilisateur dans la distribution qui fournit le comportement. Les refactorisations internes, les travaux limités aux tests, l’outillage de développement et la maintenance invisible pour l’utilisateur ne nécessitent généralement pas de note de version. Utilisez les générateurs du projet pour les fichiers de verrouillage, les références de commandes, les schémas et les autres documents générés. Examinez les différences générées, mais ne modifiez pas les fichiers générés pour dissimuler un problème dans la source de référence. Avant le transfert, exécutez les contrôles pertinents de formatage, d’analyse statique, de vérification des types, de tests, de documentation et de sélection. Consignez toute étape de contrôle volontairement omise et la raison précise pour laquelle elle ne s’appliquait pas. ## Relire tout le diff et ouvrir une demande d’intégration depuis votre copie dérivée Examinez l’ensemble des modifications de la tâche avant de publier. Confirmez que les limites architecturales, les hypothèses de sécurité, les tests, les sorties générées, les métadonnées de publication et les instructions locales concordent. Demandez confirmation avant d’effectuer une vaste refactorisation entre paquets, d’ajouter une dépendance étendue, de modifier le comportement d’une migration destructive ou de procéder à une publication externe qui n’a pas déjà été autorisée. Ne divulguez jamais de secrets, ne contournez pas les points d’accroche requis, ne modifiez pas manuellement les fichiers générés et n’exécutez aucune commande destructive de gestion de versions sans autorisation explicite. Avant toute opération distante : - Examinez les dépôts distants configurés et déterminez lequel est le dépôt de référence et lequel est la copie dérivée du contributeur. - N’envoyez pas de modifications directement vers le dépôt distant de référence ni vers sa branche par défaut protégée. - Demandez confirmation avant de renommer ou de réécrire des dépôts distants lorsque leurs rôles ne sont pas clairs. - Recherchez une demande d’intégration existante afin de ne pas dupliquer le travail. - Repositionnez les modifications sur la branche cible actuelle ou synchronisez-les autrement au moyen de la procédure acceptée par le dépôt. Utilisez un titre en langage courant, formulé à l’impératif et centré sur l’impact pour l’utilisateur. Expliquez dans le corps pourquoi la modification est nécessaire, signalez l’assistance de l’IA lorsque cela est requis et incluez les références aux tickets pertinents. Ne vous ajoutez pas comme coauteur et ne mentionnez personne, sauf si l’utilisateur l’a autorisé ou si ces personnes participent déjà à la discussion. Si une correction complète est prête, privilégiez la demande d’intégration plutôt que d’ouvrir un ticket en double. Si la modification n’est qu’une solution de contournement, une mesure d’atténuation ou une correction partielle, créez ou associez un ticket de suivi et mentionnez-le à la fois dans la demande d’intégration et près du code temporaire.