Ajouter des plugins de fournisseurs et de générateurs à un dépôt multi-module

## Compiler et tester uniquement via le lanceur de tâches du projet Le dépôt expose ses commandes de compilation, de test, d'analyse statique et d'empaquetage à travers un lanceur de tâches unique. Lisez ce fichier en premier pour découvrir les cibles disponibles, et lancez tout le travail par ces cibles. N'appelez pas directement le lanceur de tests du langage sous-jacent, l'outil d'analyse statique (linter) ni l'outillage de chart. Les cibles positionnent les tags de compilation, la portée des modules, l'environnement et les étapes de génération qu'un appel direct saute silencieusement. Un appel direct peut produire un résultat vert qui ne correspond pas à ce que produira la barrière de revue. ## Lancer la revue complète, puis vérifier en dernier le diff des fichiers générés La cible de revue agrégée unique est la barrière d'un changement, et non les vérifications individuelles qu'elle contient. Exécutez la cible agrégée plutôt que de choisir les vérifications que vous croyez pertinentes. Une fois que tout est commité, exécutez la vérification du diff généré comme étape finale. Une grande quantité de contenu généré vit en dehors de la cible de revue principale : les tests du chart d'empaquetage, les manifestes rendus et la documentation. Un arbre de travail propre après cette vérification est la preuve que tout cela a bien été régénéré. C'est le point où les changements écrits par un agent s'effondrent le plus souvent, précisément parce que cette étape semble redondante. ## Modifier les types ou modèles source, jamais les fichiers générés Les fichiers marqués comme générés appartiennent à leur générateur, pas au contributeur. Ne les modifiez jamais à la main, pas même pour une correction d'un seul caractère. Modifiez les types sources ou les modèles dont ils sont issus, puis exécutez la cible de génération, que la cible de revue agrégée inclut déjà. Une modification manuelle ne survit que jusqu'à la régénération suivante, après quoi elle disparaît sans avertissement ou produit un diff déroutant que quelqu'un d'autre devra démêler. ## Régénérer les manifestes depuis le chart et les instantanés avec la cible de mise à jour Le chart d'empaquetage est la source de vérité des manifestes de déploiement. Les manifestes statiques commités dans le dépôt en sont générés : modifiez donc le chart et régénérez, plutôt que de modifier la sortie. Les tests de schéma utilisent des tests par instantané. Après avoir changé les types de schéma, exécutez la cible de mise à jour des instantanés et relisez le diff obtenu, au lieu de modifier directement les fichiers d'instantané. Traitez un changement d'instantané inattendu comme un signal invitant à relire votre modification de type, et non comme un bruit à accepter. ## Noter les choix de conception et les compromis dans les notes de commit Attachez une note de commit à chaque commit non trivial, décrivant les décisions de conception clés, les compromis que vous avez pesés et les pièges que vous avez rencontrés. Les notes restent attachées au commit et demeurent interrogeables ensuite, ce qui préserve un raisonnement qu'un diff seul ne peut pas porter. Gardez les notes factuelles et précises : ce que vous avez choisi, ce que vous avez écarté, et pourquoi. Une note qui ne fait que redire le diff est du gaspillage. ## Ajouter les motifs peu évidents au guide partagé avant la fusion Lorsque vous découvrez un motif non évident pendant l'implémentation, ajoutez-le au document de recommandations partagé avant que le changement ne soit fusionné, et non après, quand le contexte a disparu. Gardez les entrées assez générales pour s'appliquer à l'ensemble du code, plutôt qu'à la seule fonctionnalité que vous étiez en train de construire. Un motif qui ne décrit qu'une seule extension a plutôt sa place dans la documentation propre à cette extension. ## Donner à chaque extension son module, avec les tags de compilation dans le fichier d'enregistrement Une extension optionnelle vit dans son propre module, dans un répertoire portant son nom, et le paquet de l'extension lui-même ne porte aucun tag de compilation. Les tags de compilation ont leur place dans le fichier d'enregistrement central de cette extension. Cette séparation permet au paquet de l'extension de rester compilable et testable de manière autonome, tandis que le binaire livré décide quelles extensions y sont liées. Ajoutez l'entrée de remplacement de module au fichier de module racine, dans l'ordre alphabétique. La compilation passe l'ensemble des extensions sélectionnées sous forme de tags de compilation, avec une valeur par défaut qui signifie toutes les extensions. ## Enregistrer le type de configuration de chaque extension en une ligne dans l'union partagée Le type de configuration d'une nouvelle extension va dans son propre fichier, à l'intérieur du paquet d'API partagé. Enregistrez-le en ajoutant un emplacement d'une seule ligne à la structure d'union à discriminant, où le tag de sérialisation du champ est le nom de l'extension. La résolution s'appuie sur la première clé de l'union sérialisée : ce tag doit donc être exact et unique. Imbriquez l'authentification sous une structure d'authentification dédiée. Lorsque plusieurs méthodes d'authentification sont proposées, contraignez la structure à au plus une propriété, afin que les configurations ambiguës soient rejetées au moment de l'admission plutôt qu'à l'exécution. Incluez un champ de paquet de certificats et un champ de fournisseur de certificats dès que le backend parle TLS. Une version d'API gelée accepte toujours de nouveaux emplacements d'extension ; ce sont les champs existants qui sont fermés. ## Lire les identifiants via les utilitaires partagés sans sortir de l'espace de noms La résolution des identifiants, la récupération des certificats, la validation des sélecteurs, l'analyse des métadonnées et les constantes d'étiquettes de métriques disposent toutes d'utilitaires partagés. Utilisez-les, et passez le type de magasin ainsi que l'espace de noms de la ressource consommatrice exactement comme chaque utilitaire l'attend. Le résolveur d'identifiants, en particulier, applique la règle de cantonnement à l'espace de noms qui sépare les magasins à portée de cluster de ceux qui sont rattachés à un espace de noms. Une recherche écrite à la main devient silencieusement une lecture de secret entre espaces de noms, ce qui est une élévation de privilèges, et non un problème de style. Les types d'extension qui n'ont pas de magasin passent le type de magasin vide, parce que le cantonnement par espace de noms ne s'applique pas à eux. ## Implémenter toutes les méthodes du client et renvoyer des erreurs claires pour ce qu'il ne gère pas L'interface client est obligatoire dans son intégralité ; seule la méthode de fermeture peut ne rien faire. Renvoyez l'erreur sentinelle dédiée « non trouvé » lorsqu'un secret est absent, car la politique de suppression du réconciliateur dépend de la distinction entre « absent » et « en échec ». Déclarez les capacités avec sincérité : lecture seule, écriture seule ou lecture-écriture. Une implémentation en lecture seule implémente tout de même les méthodes d'écriture et de suppression, mais doit renvoyer depuis celles-ci une erreur sentinelle, jamais une erreur nulle, qui signalerait un succès silencieux pour une opération qui n'a jamais eu lieu. Utilisez l'extracteur de chemin JSON conventionnel pour les recherches de propriétés à l'intérieur des charges utiles JSON. ## N'ajouter un cache que si la création du client est lente ou coûteuse Par défaut, pas de cache. N'en ajoutez un que lorsque la construction du client est réellement coûteuse : échange de jeton, acquisition de bail ou fédération d'identité, par exemple. Un cache par client doit être indexé par le nom, l'espace de noms et le type du magasin, et versionné par la version de ressource de l'objet magasin, afin que les modifications de configuration invalident automatiquement les entrées. Un cache par secret a sa place à l'intérieur du client, sous forme de cache à expiration et à taille bornée, et sa durée de vie ainsi que sa taille maximale doivent être des paramètres exposés à l'utilisateur plutôt que des constantes codées en dur. ## Faire passer les indicateurs de fonctionnalité de la valeur du chart jusqu'à l'initialisation Un indicateur de fonctionnalité suit un chemin fixe : une valeur du chart d'empaquetage, puis des arguments supplémentaires sur le déploiement, puis un drapeau de ligne de commande, puis l'enregistrement du drapeau, puis l'initialisation. Enregistrez les drapeaux depuis l'initialiseur du paquet de l'extension, laissez la commande racine les collecter, et exécutez l'initialisation après le démarrage du gestionnaire plutôt que pendant l'enregistrement. Les dépendances qui s'exécutent hors du processus sont livrées comme un sous-chart annexe au lieu d'être liées au binaire principal. Si une catégorie d'extension n'a aucun précédent en matière d'indicateurs de fonctionnalité, suivez le motif existant, mais attendez-vous à être le premier et signalez-le en revue. ## Partir de la commande d'échafaudage, puis compléter ce qu'elle a oublié Là où une commande d'amorçage existe pour une nouvelle extension, exécutez-la d'abord et traitez les étapes manuelles documentées comme une liste de contrôle permettant d'auditer ce qu'elle a produit et ce qu'elle a omis. Les échafaudages câblent généralement les types d'API, les fichiers de module, l'appel d'enregistrement, l'entrée de l'union à discriminant, la valeur de l'énumération de type et le branchement du résolveur. Ils ne câblent généralement pas les règles de contrôle d'accès, les pages de documentation, les extraits d'exemple, les entrées de navigation ni l'empaquetage. Parcourez explicitement la liste des éléments non couverts, au lieu de supposer que l'échafaudage a terminé le travail. ## Garder les générateurs sans état et rendre le nettoyage sûr à répéter Une extension de type générateur reçoit sa configuration sous la forme d'un blob JSON brut qu'elle désérialise elle-même, renvoie en un seul appel la carte complète des valeurs produites plutôt que clé par clé, et renvoie un blob d'état opaque qui est conservé entre la génération et le nettoyage. Soyez sans état par défaut : ne renvoyez aucun état et un nettoyage qui ne fait rien. Ne renvoyez un état que lorsqu'une ressource externe devra être libérée plus tard. Le nettoyage doit être idempotent, car le framework l'appelle pour annuler la génération lorsque la persistance de l'état échoue après celle-ci, et l'appelle de nouveau via un finaliseur lors de la suppression. ## Enregistrer les extensions dans le fichier central en évitant les noms en double Un paquet d'extension exporte un ensemble restreint et fixe de symboles de constructeur et de métadonnées, et l'enregistrement se fait dans un fichier central qui transmet ces symboles au registre. L'enregistrement panique en cas de noms en double : choisissez donc l'identifiant délibérément et vérifiez qu'il n'est pas déjà utilisé. L'enregistrement dans le schéma est distinct de l'enregistrement comportemental, et les deux sont requis : le résolveur d'exécution charge l'objet typé via le schéma, puis distribue l'appel à l'implémentation enregistrée en fonction du type. Lorsqu'un type parapluie à portée de cluster matérialise, à partir d'une spécification d'union, un objet synthétique rattaché à un espace de noms, chaque extension doit avoir un cas dans cette conversion. ## Écrire une page de documentation par extension avec les extraits partagés Rédigez une page de documentation pour l'extension en suivant l'ordre de sections conventionnel : introduction, authentification ou configuration, spécification de la ressource consommatrice, puis tout flux optionnel d'envoi ou d'écriture. Placez les exemples exécutables dans le répertoire d'extraits partagés et transcluez-les dans la page au lieu de dupliquer le texte, afin qu'une seule correction se propage partout. Documentez un schéma d'authentification partagé une seule fois sur une page autonome et faites-y référence depuis les pages propres à chaque service, au lieu de le recopier dans chacune. Ajoutez l'entrée de navigation en bas de la section concernée, l'ordre étant historique et non alphabétique. ## Travailler uniquement en local, sans push ni publication Les agents peuvent inspecter le dépôt, expliquer le code, proposer des changements, modifier des fichiers locaux, écrire des tests, mettre à jour la documentation, exécuter des vérifications et préparer un diff local destiné à une revue humaine. Les agents ne doivent pas créer de pull requests, pousser des branches, publier des versions, téléverser des paquets, modifier les paramètres du dépôt, modifier les permissions, faire tourner des identifiants, modifier des secrets, ni effectuer aucune autre action d'écriture externe. S'il vous est demandé d'effectuer une action bloquée, ne l'effectuez pas. Créez plutôt un fichier local qui consigne l'action demandée, la raison pour laquelle elle est bloquée, le travail local qui a été réalisé le cas échéant, et les étapes manuelles qu'un contributeur humain devra ensuite suivre. ## Vérifier un diff minimal et les tests lancés avant de déclarer le travail fini Avant de présenter un travail comme terminé, vérifiez que l'intention est documentée, que le diff est minimal et chirurgical et ne touche aucun commentaire ni code adjacent sans rapport avec le travail, que les tests pertinents ont été exécutés via le lanceur de tâches du projet, et que la documentation a été mise à jour. Si une partie de la validation n'a pas pu être menée à bien, dites-le explicitement et expliquez pourquoi, plutôt que de présenter comme achevé un changement partiellement vérifié.