Modifier une extension multi-navigateur sans divulguer de secrets ni casser les données enregistrées

## Repérer d’abord la couche concernée de l’extension et ses règles locales Avant de modifier le code, identifiez la couche touchée : logique d’arrière-plan, interface utilisateur, utilitaires partagés, déclarations du navigateur, outils de construction, tests ou mises à niveau de l’état stocké. Lisez les instructions propres à la couche la plus proche avant toute modification ; les fichiers d’automatisation du flux de travail comportent souvent des raccordements supplémentaires et des règles de file de fusion. Utilisez l’environnement d’exécution géré par le dépôt et l’enveloppe du gestionnaire de paquets. Conservez la configuration dans le fichier d’environnement local prévu, jamais dans les sources suivies. Préférez le langage typé actuel pour chaque nouveau fichier d’implémentation ; les anciens fichiers non typés peuvent rester en place jusqu’à ce qu’une modification demandée justifie leur conversion. Utilisez le formateur attribué à chaque famille de fichiers. Le formateur de code prend en charge les fichiers typés et les composants, tandis que celui des données structurées prend en charge les données des paquets et de configuration. Avant la remise, exécutez le formatage des fichiers modifiés, les vérifications des types statiques, du lint et des dépendances circulaires. Gardez des fonctions ciblées, réduisez l’imbrication par des retours anticipés, retirez la logique répétée uniquement si son extraction clarifie la responsabilité, et ne laissez ni journalisation de débogage ni code mis en commentaire. ## Garder les secrets en local et régénérer les politiques après un changement de dépendances Traitez les identifiants d’API, les points de terminaison de surveillance, les mots de passe de test et le matériel de signature comme des secrets locaux. Fournissez des espaces réservés documentés, mais ne consignez jamais de valeurs réelles dans le dépôt et n’incluez aucun état sensible dans les journaux de diagnostic. Chaque ajout, mise à niveau ou retrait de dépendance constitue une modification de la chaîne d’approvisionnement. Exécutez toute la séquence : 1. Mettez à jour la déclaration du paquet et le fichier de verrouillage. 2. Dédupliquez le fichier de verrouillage avec la commande prise en charge. 3. Recalculez la liste des paquets autorisés à exécuter des scripts d’installation. 4. Régénérez les politiques de capacités qui limitent l’accès des dépendances aux API de l’hôte. 5. Régénérez les mentions d’attribution des tiers. 6. Construisez et testez avec la politique de sécurité de production activée. Incluez dans la même revue toutes les modifications générées des politiques et des attributions. Une construction de développement sans politique peut servir aux itérations rapides, mais elle ne remplace jamais la construction finale protégée. Régénérez les politiques sensibles à la plateforme sur la plateforme cible, au lieu de les affaiblir pour faire réussir une construction. ## Concevoir les contrôleurs d’arrière-plan avec un état déclaré et des actions du domaine Utilisez des contrôleurs pour la logique métier en arrière-plan et la communication par messages entre les sous-systèmes. Pour chaque propriété stockée, déclarez si elle est anonyme, sûre pour les instantanés de diagnostic ou les journaux d’état, persistante et utilisée par l’interface. Respectez ces règles d’état : - Exportez une fabrique d’état par défaut qui renvoie un nouvel objet, jamais un objet par défaut mutable et partagé. - Recevez les dépendances du constructeur dans un seul objet d’options nommé plutôt que par des arguments positionnels. - Modélisez les actions du domaine telles que l’ajout, le retrait, l’approbation ou le rejet ; évitez les méthodes génériques de définition de champs. - Ne stockez que l’état essentiel et dérivez les décomptes, les indicateurs et les projections au moyen de sélecteurs exportés. - Validez les entrées des actions avant de mettre à jour l’état. - Implémentez le nettoyage du cycle de vie pour les minuteurs, abonnements, écouteurs et canaux de messages, puis déléguez au nettoyage du contrôleur parent. Maintenez synchronisés le code source du contrôleur, les types, les tests colocalisés, l’enregistrement et les sélecteurs touchés. Une modification de la structure de l’état exige également une étape de mise à niveau numérotée. ## Placer le code dans la couche responsable et mettre à jour les fichiers liés Placez les composants d’interface réutilisables avec leurs styles, types, tests, scénarios, documentation et export public. Placez les composants propres à une page dans la couche de cette page, les auxiliaires propres à l’arrière-plan avec le code d’arrière-plan, et les utilitaires, constantes et types véritablement partagés dans des modules communs. Lorsque le comportement change, examinez les fichiers directement couplés : - Les modifications d’un contrôleur peuvent nécessiter des tests, des types, un enregistrement et des mises à niveau d’état. - Les modifications des propriétés d’un composant peuvent nécessiter des tests, des scénarios, des styles, de la documentation et des exports. - Les modifications de l’état global peuvent nécessiter des sélecteurs et les composants qui les utilisent. - Les modifications de la construction ou des déclarations du navigateur peuvent nécessiter des dispositifs de test propres à la cible et une couverture de bout en bout. Ne copiez pas de logique partagée uniquement pour éviter de choisir un responsable. Déplacez-la vers la couche commune la plus étroite, utilisez l’injection de dépendances si nécessaire et résolvez les importations circulaires au lieu d’accepter une liste d’exceptions élargie. ## Construire et tester séparément chaque navigateur cible et chaque indicateur de fonctionnalité Conservez une voie de construction et de test distincte pour chaque génération prise en charge des déclarations de navigateur. Tenez compte des différences entre les pages d’arrière-plan persistantes et les service workers, ainsi que des modèles de permissions et de la disponibilité des espaces de noms. Utilisez l’abstraction d’API multi-navigateur dans le code partagé. Isolez les différences inévitables entre les cibles dans une petite couche de compatibilité, au lieu de disperser les conditions dans les fonctionnalités. Les indicateurs de fonctionnalités doivent être des entrées de construction explicites : - Utilisez la configuration locale documentée pour un développement reproductible. - Utilisez des substitutions d’environnement par une seule commande pour les expériences isolées. - Utilisez une substitution locale de déclaration uniquement pour les scénarios de test d’indicateurs distants. - Construisez et testez la même combinaison de cible et d’indicateurs que celle qui sera livrée. Si l’utilisateur ne précise aucun navigateur, utilisez la cible par défaut documentée du projet. Lorsque la demande nomme une cible, choisissez les commandes correspondantes de développement, de production et de bout en bout au lieu de supposer la compatibilité à partir d’une autre construction. ## Créer les composants d’interface et n’optimiser qu’après mesure Utilisez des composants fonctionnels et des hooks, déstructurez les propriétés à la frontière, conservez localement l’état exclusivement local et n’utilisez la couche d’état partagé que pour les données qui traversent plusieurs fonctionnalités. Pour garantir l’exactitude et les performances du rendu : - Utilisez des identifiants de domaine stables comme clés des listes dynamiques, jamais les positions du tableau. - Calculez les valeurs d’affichage dérivées pendant le rendu, au lieu de les copier dans l’état au moyen d’un effet. - Ne mémoïsez les opérations coûteuses de tri, de filtrage ou d’agrégation que lorsque le travail répété est significatif. - Stabilisez les fonctions de rappel transmises aux enfants mémoïsés lorsque les changements de référence provoquent de nouveaux rendus. - Définissez les objets et styles véritablement statiques en dehors du composant. - Envisagez la virtualisation des grandes listes après avoir mesuré le coût du rendu. Copiez avant de trier lorsque les entrées sont immuables. Profilez en premier les composants souvent rendus ou coûteux en calcul ; n’ajoutez pas de mémoïsation sans preuve aux composants simples et rarement rendus. ## Reproduire le bug par un test en échec, corriger puis retester Pour un défaut, ajoutez d’abord un test ciblé qui reproduit l’échec, exécutez-le et confirmez son échec, implémentez la plus petite correction, confirmez la réussite du test, puis exécutez la couverture directement associée. Placez les tests unitaires avec le code source et testez le comportement par les interfaces publiques plutôt que par les méthodes privées. Utilisez des tests d’intégration pour les frontières entre sous-systèmes. Utilisez des tests de bout en bout pour les flux de travail réels du navigateur et construisez d’abord l’artefact de test dédié. Pendant les itérations, une construction non protégée plus rapide peut être acceptable ; la vérification finale doit utiliser la politique de sécurité de production et le navigateur cible demandé. Lorsqu’une vérification visuelle est explicitement demandée : 1. Lancez l’environnement de test réel de l’extension. 2. Examinez l’écran actuel avant d’agir. 3. Parcourez le flux utilisateur avec les commandes du navigateur. 4. Effectuez une capture d’écran ou consignez une description de l’écran final comme preuve. 5. Nettoyez la session de test même après un échec. Si l’outil visuel requis n’est pas disponible, signalez cette limite et ne prétendez pas avoir effectué une vérification visuelle à partir de la seule inspection du code. Examinez les modifications des instantanés avant de les accepter ; ne mettez à jour un instantané que lorsque le changement de comportement est intentionnel. ## Écrire une mise à niveau numérotée quand la forme des données enregistrées change Créez une mise à niveau numérotée chaque fois que la structure de l’état persistant change. Générez-la avec l’outil du dépôt afin que l’ordre et l’enregistrement restent cohérents. Une mise à niveau doit : - accepter correctement les entrées anciennes, incomplètes et partiellement endommagées ; - cloner l’entrée et renvoyer un nouvel objet d’état au lieu de modifier la valeur de l’appelant ; - transformer uniquement la plage de versions et les propriétés dont elle est responsable ; - enregistrer explicitement la version cible ; - préserver les données utilisateur sans rapport. Testez des états anciens représentatifs, les champs absents, les valeurs facultatives mal formées, les attentes d’idempotence et la nouvelle sortie exacte. Exécutez à la fois le test de mise à niveau et les tests du contrôleur ou de la fonctionnalité qui consomment l’état mis à niveau. ## Classer les erreurs et les corriger sans désactiver les contrôles Lisez la première erreur exploitable avant de modifier l’environnement. Classez-la comme erreur de formatage, de type, de dépendance, de politique de capacités, de construction du navigateur, de données de test, d’artefact obsolète, de port ou d’importation circulaire, puis exécutez le diagnostic le plus ciblé pour cette catégorie. Lorsqu’un test qui réussissait auparavant échoue après la modification, déterminez si l’implémentation a régressé ou si le comportement attendu a changé intentionnellement. Ne mettez le test à jour que dans le second cas et documentez la raison fonctionnelle. Pour les échecs de bout en bout, vérifiez que la construction de test correcte et actuelle existe, utilisez la sortie de débogage et ne laissez le navigateur actif que pendant une inspection en cours. Pour les échecs de politique, régénérez la politique à partir des dépendances déclarées et de l’accès à l’hôte ; ne désactivez pas durablement son application. Ne retirez les caches, les sorties de construction, les paquets installés, les données du navigateur ou les instantanés qu’après avoir déterminé la cible exacte et confirmé que leur régénération est sûre. N’utilisez pas un nettoyage étendu comme première étape de dépannage. ## Faire commits, pushs et demandes de revue uniquement sur demande Ne modifiez pas la configuration du dépôt et n’exécutez aucune commande destructive de gestion des versions. N’effectuez aucun stage, commit ou push et n’ouvrez aucune demande de revue, sauf si l’utilisateur a explicitement demandé cette action précise. Après autorisation : - N’incluez dans le stage que les fichiers appartenant à la modification demandée. - Formatez et testez la surface modifiée avant le commit. - Utilisez la convention structurée de commits du dépôt. - N’effectuez un push que s’il a été demandé. - Ouvrez une demande de revue en brouillon, sauf si l’utilisateur a explicitement demandé le statut prêt. - Suivez le modèle de revue et masquez entièrement les sections non applicables. Les sections de tests manuels doivent décrire les actions humaines et les résultats visibles, pas des commandes automatisées de lint ou de test. Incluez des preuves avant et après pour les modifications visibles de l’interface, expliquez les décisions qui ne sont pas évidentes, liez les travaux associés et indiquez les notes de modification destinées aux utilisateurs si nécessaire. Pendant la revue, répondez aux commentaires et ajoutez des commits de suivi au lieu de réécrire l’historique déjà examiné. Avant la fusion, exigez des conversations résolues, des approbations, une automatisation réussie et le titre de squash attendu par le dépôt. Terminez par une liste de contrôle proportionnée : formatage des fichiers modifiés, types, dépendances circulaires, tests ciblés, constructions touchées, fichiers associés, documentation, politiques de capacités de production lorsque les dépendances changent et preuves visuelles réelles lorsqu’elles sont demandées.