Modifier par petites touches une bibliothèque d'interface avec état sans casser ses utilisateurs

## Trouver le propriétaire de l'état et ne le modifier que là où la bibliothèque le permet Commencez par identifier le composant propriétaire de l'état, la frontière de mise à jour et le contrat public concernés par la demande. Dans un modèle d'état immuable, effectuez les lectures depuis un instantané cohérent et ne modifiez l'état que dans le contexte de mise à jour autorisé par la bibliothèque. Traitez les références de nœuds ou d'entités comme des références versionnées ; ne conservez pas d'hypothèses de mutabilité d'une frontière de mise à jour à l'autre. Maintenez l'enregistrement des fonctionnalités, les commandes, les transformations et les écouteurs dans leur cycle de vie documenté. Pour tout nouveau travail, privilégiez le mécanisme actuel d'extension ou de composition, tout en préservant les anciens parcours d'intégration encore pris en charge. Veillez à ce que chaque enregistrement dispose d'un parcours de nettoyage clair et conservez les formats de sérialisation que les utilisateurs existants pourraient encore charger. ## Chercher avec des outils qui comprennent la syntaxe et garder le changement petit Utilisez une recherche et une réécriture sensibles à la syntaxe lorsqu'une modification concerne des imports, des sites d'appel, des annotations de type ou du code structuré. Les expressions régulières orientées ligne peuvent manquer les formes multilignes et correspondre à des identifiants sans rapport. Confirmez les correspondances candidates dans l'arbre syntaxique avant d'appliquer une réécriture étendue. Maintenez la modification centrée sur le comportement et limitée à son périmètre. Utilisez des noms propres au domaine, des clauses de garde pour les états invalides ou déjà traités et un parcours de réussite clairement visible. N'extrayez une fonction auxiliaire que si elle nomme une responsabilité ou simplifie le code appelant. Ne mélangez pas de remaniement opportuniste, de journalisation de débogage, de noms temporaires ni de mise en forme sans rapport dans la modification finale. Lorsqu'une fabrique sans effet secondaire est créée au niveau du module, respectez la convention d'annotation du projet pour l'élimination du code inutilisé et mettez à jour la règle qui l'impose si la famille de fabriques elle-même s'agrandit. ## Garder les API publiques compatibles et utiliser le document et la window de l'élément Supposez que le code externe dépend des noms publics, des signatures, du comportement et des données sérialisées existants. Privilégiez les ajouts d'API et les paramètres facultatifs. Lorsqu'une modification incompatible est inévitable, conservez l'ancien parcours et marquez-le comme obsolète avant de le retirer, puis vérifiez à la fois le parcours actuel et celui de compatibilité. Maintenez tous les systèmes de types pris en charge et toutes les surfaces de déclarations générées touchés par l'API. Le code destiné au navigateur doit obtenir les objets document et window associés depuis la racine ou l'élément concerné, plutôt que de dépendre des objets globaux ambiants. Utilisez des fonctions auxiliaires tenant compte du contexte pour la sélection, le focus, la cible d'événement et le parcours des parents, afin que les racines fantômes et les documents intégrés ne lisent pas silencieusement dans le mauvais environnement. Pour les modifications concernant la sérialisation, le traitement des requêtes, les URL, la production de HTML ou de scripts, les chemins du système de fichiers, l'authentification ou les dépendances, identifiez l'entrée non fiable et la protection de validation la plus proche. Privilégiez un comportement bloquant par défaut en cas d'échec, gardez les secrets hors des journaux et des artefacts, et vérifiez les côtés émetteur et lecteur de tout protocole. ## Écrire d'abord un test qui échoue et choisir entre test unitaire ou en vrai navigateur Pour une modification de comportement ou une correction de défaut, définissez d'abord l'invariant observable. Ajoutez ou mettez à jour le test ciblé le plus proche, exécutez-le avant l'implémentation lorsque c'est possible et confirmez qu'il échoue pour la raison attendue. Apportez la modification minimale qui le satisfait, réexécutez le test ciblé, puis n'étendez la vérification qu'à ce qu'exige la surface touchée. Utilisez des tests unitaires en environnement simulé pour la logique qui ne dépend pas de la disposition réelle ni du comportement de sélection. Utilisez des tests dans un navigateur réel pour la disposition, la sélection, le focus, les racines fantômes ou le comportement entre documents. Réservez les tests de bout en bout à la navigation, à l'intégration complète de l'application ou aux protocoles qui nécessitent un système en cours d'exécution. Construisez l'artefact précis consommé par le test avant de vous fier à son résultat. Ne remplacez pas sans raison un test ciblé par une commande étendue à tout le dépôt. La réussite d'une suite sans rapport ne prouve pas la validité de la frontière modifiée. ## Relire les différences et ajouter la note de publication avant de finir Avant de terminer, examinez les différences comme le ferait une personne qui vient de rejoindre le projet. Confirmez que les noms expriment le sens du domaine, que les cas limites utilisent des gardes explicites, que le parcours principal est lisible, que le nettoyage est complet et qu'aucun contrat public n'a changé accidentellement. Exécutez l'outil de formatage, l'analyseur de règles, le vérificateur de types ou la tâche d'instantané d'API exigés par le paquet concerné. Ajoutez la note de publication ou l'entrée du journal des modifications prévue par le dépôt lorsque le comportement publié change. Décrivez la correction ou la fonctionnalité visible par l'utilisateur plutôt que les détails d'implémentation. N'incluez aucun lien de session privée, identifiant d'accès ni référence réservée à un usage interne dans les messages de commit et les demandes de modification, et consignez les preuves issues des tests ciblés qui étayent le changement.