Modifier ensemble les versions synchrone et asynchrone d'une bibliothèque cliente sans casser l'API

## Repérer le comportement public à ne pas changer avant de modifier Avant toute modification, identifiez le comportement public, les versions d’environnement d’exécution prises en charge, l’architecture concernée et le plus petit ensemble de fichiers responsable du changement. - Considérez les signatures publiques, les noms d’arguments, les valeurs par défaut, les types de retour, les exceptions et le comportement dans les cas limites comme des contrats de compatibilité. - Repérez toutes les implémentations parallèles du même comportement, notamment les clients synchrones et asynchrones. - Identifiez les couches de routage, d’analyse, de politique, de connexion et de mise en forme des réponses susceptibles d’intervenir dans le comportement. - Lisez les implémentations, les tests et les surcharges de types à proximité avant de choisir un modèle. - Préservez la sémantique actuelle du protocole et du serveur, sauf si la modification demandée exige explicitement autre chose. - N’étendez pas la tâche à des travaux de nettoyage sans rapport. Si le comportement demandé entre en conflit avec un invariant documenté, arrêtez-vous et signalez ce conflit au lieu de redéfinir silencieusement le contrat. ## Appliquer le même changement aux clients synchrone et asynchrone Lorsqu’une bibliothèque fournit des piles clientes équivalentes, considérez leur parité comme une propriété obligatoire. 1. Associez le symbole synchrone modifié à son équivalent asynchrone, ou inversement. 2. Comparez les signatures, les surcharges, les annotations de types, les valeurs par défaut, les formes de retour, les erreurs et les effets secondaires. 3. Appliquez un comportement équivalent dans les deux piles, sauf si une différence d’environnement d’exécution documentée rend cela impossible. 4. Maintenez la cohérence des interfaces de commandes partagées, des tables de routage, des fonctions de rappel des analyseurs et des métadonnées de politique. 5. Ajoutez des tests associés lorsque les deux piles exposent le comportement. Utilisez la syntaxe de types et les conventions de surcharge établies dans la base de code. Si un seul côté doit changer, consignez la raison architecturale précise et vérifiez que cette asymétrie est intentionnelle. ## Ne modifier que la couche responsable et réutiliser les fonctions utilitaires existantes Privilégiez une modification ciblée qui réutilise les utilitaires et les conventions existants. - Modifiez uniquement la couche responsable du comportement. - Préservez les interfaces publiques et la sémantique des erreurs. - Évitez les nouvelles dépendances, sauf si les moyens existants ne permettent pas de satisfaire l’exigence. - Évitez les nouvelles abstractions lorsqu’un utilitaire ou un modèle actuel suffit. - Limitez les importations et placez-les au niveau du module, sauf si une importation différée est techniquement nécessaire. - Mettez à jour les chaînes de documentation lorsque le comportement change et maintenez-les cohérentes avec les types. La correction est prioritaire. N’optimisez qu’une fois le comportement correct et ne sacrifiez jamais la correction pour réduire les allocations ou accélérer l’exécution. ## Ne pas ralentir les chemins critiques ni changer le comportement du protocole Examinez les modifications apportées aux chemins fréquemment exécutés afin de repérer les allocations évitables, les analyses répétées, le travail en double et les grandes structures temporaires. - Réutilisez les utilitaires établis et les métadonnées mises en cache. - Préservez le choix du protocole réseau indépendamment de la mise en forme des réponses destinées à l’utilisateur. - Maintenez la cohérence des politiques de routage et d’agrégation avec la sémantique des commandes. - Le cas échéant, traitez explicitement les redirections, les nouvelles tentatives, les différences de topologie et la propagation des erreurs. - Ne normalisez pas silencieusement un cas limite que le service sous-jacent distingue explicitement. Les modifications de performances doivent conserver un comportement observable identique. Si une optimisation complique la correction ou la parité, préférez l’implémentation correcte la plus simple. ## Tester d'un cas en échec jusqu'à la matrice de tests complète Établissez les preuves en élargissant progressivement le périmètre : 1. Ajoutez ou mettez à jour un test déterministe qui échoue avant la correction. 2. Exécutez le plus petit test ou ensemble de tests pertinent. 3. Exécutez la couverture miroir des variantes synchrones et asynchrones. 4. Vérifiez des combinaisons pertinentes de protocole, de mode de réponse, de topologie ou de fonctionnalités facultatives. 5. Exécutez les analyses statiques, les vérifications de formatage et les vérifications de types exigées par le projet. 6. Exécutez toute la matrice de tests prise en charge lorsque la modification peut affecter un comportement partagé. N’affaiblissez pas les assertions, ne retirez pas de couverture et ne reclassez pas les échecs dans le seul but de faire réussir l’ensemble de tests. Les tests nécessitant une infrastructure externe doivent rester clairement séparés des ensembles locaux par défaut. ## Examiner les différences finales pour repérer le code de débogage et les écarts entre synchrone et asynchrone Avant de terminer, examinez la modification complète et vérifiez les points suivants : - seuls les fichiers et les lignes concernés ont été modifiés ; - il ne reste aucun code de débogage, aucune suppression accidentelle ni aucun changement de formatage sans rapport ; - les interfaces publiques et le comportement des erreurs sont inchangés, sauf intention explicite ; - les implémentations miroirs et les annotations de types restent alignées ; - les tests couvrent les cas de réussite, les cas limites et les chemins d’échec ; - les analyses statiques et les ensembles de tests requis réussissent ; - la documentation correspond au comportement mis en œuvre ; - aucune dépendance, allocation ou abstraction inutile n’a été introduite. Corrigez chaque problème détecté et répétez les vérifications concernées. Indiquez ce qui a changé, ce qui a été validé et tout scénario externe explicitement non testé, sans prétendre avoir effectué une vérification plus large.