Modifier un paquet serveur public que d’autres étendent sans casser leur code

## Vérifier ce qui est publié et garder les secrets hors du paquet Avant toute modification, identifiez la cible de publication, la licence, le système de modules, le langage, le rôle à l’exécution et le chemin de synchronisation du paquet. Traitez chaque fichier d’un paquet synchronisé publiquement comme le contenu d’une version publique, même si le développement a lieu dans un espace de travail privé. - Ne placez jamais de secrets, de comportements soumis à une licence ou de données de test réservées à un usage interne dans le paquet public. - Maintenez les paquets réservés au serveur sans interface utilisateur ; n’introduisez aucune dépendance au navigateur ou au DOM. - Respectez les conventions de modules et de langage réellement employées par le paquet au lieu d’importer les modèles de paquets voisins. - Recensez les dépendants directs dans l’espace de travail et supposez qu’il existe d’autres utilisateurs externes du paquet. La diffusion publique élargit le rayon d’impact, même si un seul dépendant est visible dans l’espace de travail. ## Garder fonctionnels les anciens callbacks et les chemins d’import profonds Ne transformez pas silencieusement les fonctions de rappel en promesses ou en fonctions asynchrones. Dans un code mêlant des pratiques de différentes époques, un point d’accroche d’extension peut dépendre de la forme du rappel, même si les points d’appel voisins sont synchrones ou fondés sur des promesses. Avant de modifier un appel : 1. Recensez toutes les implémentations du point d’extension. 2. Comparez l’ordre des arguments, le comportement de retour, le moment du rappel et la sémantique des erreurs. 3. Respectez le style du fichier modifié. 4. Ajoutez ou mettez à jour les tests pour chaque forme d’appel prise en charge. Ne renommez et ne déplacez aucun fichier d’utilitaire, de middleware ou de modèle paraissant interne avant d’avoir recherché les imports profonds dans les dépôts en aval. Un import par chemin source constitue une API publique implicite et peut cesser de fonctionner sans avertissement du compilateur. ## Respecter l’ordre des middlewares et les noms exacts des hooks Préservez explicitement les dépendances entre middlewares. L’authentification ou la résolution du jeton doit s’exécuter avant les contrôles d’autorisation lorsque l’autorisation lit le contexte utilisateur déjà renseigné. Traitez les changements d’ordre comme des changements de contrat, et non comme un nettoyage de mise en forme. Pour un nouveau middleware, reprenez la forme de fabrique établie du paquet, par exemple une fabrique adaptée au paquet qui renvoie un gestionnaire de requêtes, puis enregistrez-la à l’endroit prévu dans la chaîne centrale. Utilisez le mécanisme existant de points d’accroche de modification comme surface d’extension. Recherchez tous les noms et toutes les implémentations de points d’accroche actuels avant d’ajouter un point d’appel. Confirmez le nom exact, la valeur d’entrée, la forme du rappel ou du retour et le comportement par défaut ; un nom mal orthographié peut renvoyer silencieusement la valeur par défaut. Documentez chaque nouveau point d’extension à un endroit où les responsables des implémentations en aval pourront le trouver. ## Ajouter de nouvelles migrations au lieu de modifier celles déjà livrées Suivez les abstractions de base établies au lieu d’inventer des modèles parallèles. Les nouveaux modèles de données doivent utiliser le module de modèle partagé ou la structure de base. Les nouvelles ressources REST de premier niveau doivent étendre la base de ressources commune et enregistrer leurs routes par l’intermédiaire du point d’entrée central. Traitez les migrations de base de données déjà distribuées comme immuables et à sens unique : - ne modifiez jamais une migration existante après sa publication ; - ajoutez une nouvelle migration numérotée pour chaque correction ultérieure ; - rendez chaque migration idempotente ; - tenez compte des interruptions et des exécutions répétées au démarrage ; - vérifiez le comportement sur des bases de données neuves comme sur des bases déjà migrées. Lorsque des paquets en aval injectent des champs ou des comportements de modèle au moyen de points d’accroche, contrôlez ces points d’injection avant de modifier les schémas, les valeurs par défaut, la sérialisation ou l’hydratation. ## Trouver les paquets touchés par un changement et tester les deux côtés Reliez une modification à ses utilisateurs avant de la mettre en œuvre. Coordonnez-vous avec les appelants en aval lorsque vous modifiez le middleware d’authentification, la gestion des autorisations, les limites de session, les utilitaires partagés, les fonctions de chiffrement, les points d’accroche de modèle ou les signatures de points d’extension. Traitez les utilitaires importés en profondeur comme des API publiques. Traitez la propriété respective des jetons et des sessions comme une limite architecturale. Lorsqu’une valeur est stockée sous forme de référence et hydratée à la lecture, contrôlez l’auteur de l’écriture et le processeur de déréférencement avant de modifier sa représentation. Pour chaque modification transversale : 1. Lisez les notes pertinentes sur l’architecture, les dépendances et les pièges connus. 2. Recherchez les implémentations et les points d’appel en aval. 3. Énoncez le contrat qui doit rester valide. 4. Testez les deux côtés de la limite. 5. Documentez toute modification volontaire du contrat et son chemin de migration. ## Tester les valeurs qui traversent la limite de la machine virtuelle Les modifications apportées aux bundles de machine virtuelle, aux couches de compatibilité, aux instances d’évaluateur, aux limites de ressources ou à la sémantique des erreurs exigent un contrôle complet du contrat client-serveur. Maintenez la parité entre les couches de l’hôte et de l’environnement isolé, reconstruisez le bundle et vérifiez que les valeurs franchissent intactes la limite d’exécution. Ne supposez pas que les objets actifs de la base de données conservent leur identité ou leurs prototypes après une sérialisation au travers d’un environnement d’exécution isolé. Testez les identifiants, les références, les dates, les tampons, les erreurs et les valeurs hydratées dans les deux sens. Soyez attentif aux modifications de l’état de l’hôte à l’échelle du processus que peuvent provoquer des couches de compatibilité initialisées au chargement d’un module. Un contexte de navigateur simulé peut créer un état global même si le paquet est censé rester sans interface utilisateur. Traitez le code du bundle exclu de la couverture comme une lacune de test connue et ajoutez des contrôles d’exécution ciblés au lieu de supposer que la couverture habituelle suffit à le prouver. ## Détecter au démarrage les fonctions de la base de données et prévoir une solution de repli Prenez en charge plusieurs implémentations de base de données en sondant leurs capacités au démarrage. Conditionnez les collations avancées, les pipelines de recherche, les index composés sur des chemins imbriqués et les autres fonctionnalités dépassant le niveau de base au résultat du sondage, et fournissez une solution de repli testée. Ne déduisez jamais la compatibilité du nom d’un produit ou d’une chaîne de version lorsque l’environnement d’exécution fournit une carte des capacités. Les modifications annulées à plusieurs reprises prouvent que le chemin de sondage et de repli fait partie du contrat. Lorsque le comportement du paquet public dépend d’un indicateur de fonctionnalité, mais que le paquet ne peut pas importer le registre privé, appelez le point d’accroche d’extension établi avec la chaîne de clé exacte de l’indicateur. Vérifiez la clé dans le registre et testez les chemins activé et désactivé. N’intégrez pas la logique du registre privé au paquet public. ## Lancer les tests, le lint et le build que le paquet possède vraiment Définissez l’état « réussi » à partir des scripts réellement fournis par le paquet. Pour un paquet uniquement en JavaScript, cela peut signifier la suite de tests complète et le linter, sans inventer une étape de vérification de types inexistante. Exécutez la compilation lorsque la modification affecte la sortie d’exécution incluse dans le bundle. Enregistrez chaque nouveau fichier de test dans l’importateur central de la suite lorsque la détection n’est pas automatique ; un fichier de test non enregistré n’offre aucune protection. Utilisez le filtre de noms de tests pris en charge pour limiter l’enquête, mais exécutez toute la suite requise avant de terminer. Manipulez avec prudence les commandes lint qui appliquent des corrections automatiques et examinez leur diff. Confirmez que les tests, le lint et la compilation du bundle concerné réussissent, et conservez les avertissements qui révèlent des problèmes d’exécution ou de compatibilité. ## Confirmer tout l’impact avant de déclarer le changement terminé Commencez par le contrat concerné, et non par le fichier le plus proche. Recherchez les pièges connus et les dépendances en aval, effectuez la plus petite modification compatible et vérifiez la sécurité de la publication avant d’annoncer la fin des travaux. La relecture finale doit confirmer : - qu’aucun secret, contenu soumis à restriction ou élément réservé à un usage interne n’a intégré le paquet public ; - que les contrats relatifs aux rappels, aux points d’accroche, aux imports profonds et à l’ordre des middlewares restent valides ; - que les migrations sont additives et idempotentes ; - que les limites des modèles, des références, des machines virtuelles et des capacités de base de données ont été testées lorsqu’elles étaient concernées ; - que les nouveaux tests sont enregistrés et que les véritables contrôles qualité du paquet réussissent ; - que les appelants entre paquets et la documentation ont été mis à jour lorsque cela était nécessaire ; - que toute modification incompatible ou de version majeure a été coordonnée avec toutes les cibles de publication. Ne qualifiez pas une modification d’isolée uniquement parce que le nombre de dépendances dans l’espace de travail est faible ; les utilisateurs publics restent inclus dans le modèle de risque.