Garder en ordre le dépôt de code d’un produit avec une app et une ligne de commande

## Suivre d’abord le fichier de règles principal, puis les règles de chaque dossier Traitez le fichier de directives racine comme la source de vérité de tout le dépôt pour les limites transversales, les processus de travail et les commandes. Gardez-le suffisamment concis pour orienter les nouvelles personnes contributrices sans dupliquer les détails des modules. - Publiez un index court vers les documents relatifs au produit, à l’architecture, aux contributions, aux révisions et aux plans en cours. - Marquez clairement les spécifications archivées et ne considérez jamais des décisions anciennes comme le comportement actuel. - Dirigez chaque répertoire principal vers son propre fichier de directives concernant les responsabilités et contraintes locales. - Avant de travailler dans un répertoire régi par des règles, lisez ses directives locales en plus des règles racines. - Lorsque deux documents se contredisent, suivez la source de vérité désignée et signalez le conflit au lieu de les mélanger. Ne recopiez pas les règles propres aux modules dans le document racine. Mettez à jour une règle au niveau le plus précis qui la couvre entièrement et ajoutez un lien depuis les documents plus généraux lorsque cela est nécessaire pour la trouver. ## Décider où vont le nouveau code et les nouveaux tests avant de modifier Maintenez une carte du dépôt qui explique ce que possède chaque zone de premier niveau et quelles dépendances peuvent franchir ses limites. Utilisez cette carte pour décider où placer le nouveau code, les tests, les modèles, la documentation et les données d’exécution. - Séparez les applications destinées aux utilisateurs, les contrats partagés, les composants fondamentaux de la plateforme, les outils d’orchestration, les tests de bout en bout et les extensions de contenu. - Maintenez la logique métier des applications indépendante des détails internes de contrôle des processus et de conditionnement. - Empêchez une application d’importer les sources privées ou les tests d’une autre application. - Transférez les DTO, événements, erreurs et formes de tâches interenvironnements vers une couche pure de contrats partagés. - Conservez les tests dans le répertoire appartenant à la couche qu’ils vérifient ; placez les tests de cohérence entre applications dans la couche de bout en bout. - Consignez les répertoires retirés ou inactifs afin que les personnes contributrices ne recréent pas accidentellement une architecture obsolète. Si un besoin réutilisable n’a pas de responsable clairement établi, arrêtez-vous et obtenez une décision de responsabilité avant de créer un autre emplacement partagé. ## Fixer à un seul endroit où les données sont stockées, puis le transmettre Résolvez chaque racine, espace de noms et identité d’exécution une seule fois à la limite responsable, puis transmettez la valeur résolue aux composants en aval. Les composants doivent utiliser cette valeur au lieu de la reconstruire à partir de ports, de répertoires de travail, de noms d’applications ou de valeurs de secours de l’environnement. - Dérivez tous les chemins de données appartenant à l’environnement d’exécution de la racine de données résolue ou de constantes qui en découlent. - Traitez les substitutions limitées et les sources de migration comme des exceptions explicites, et non comme des racines de remplacement. - Séparez les détails transitoires du transport de l’identité persistante de l’environnement d’exécution. - Attribuez des espaces de noms aux états conditionnés et de développement avant de démarrer les processus enfants. - Transmettez l’état résolu aux processus enfants ; ne les laissez pas deviner leurs propres emplacements de stockage. - Documentez les anciens chemins de contournement connus comme candidats au retrait et ne les utilisez jamais comme exemples. Lorsqu’une correction évidente existe, acheminez le chemin par la racine canonique ou un argument explicite. Lorsque la responsabilité correcte n’est pas claire, demandez une décision des responsables au lieu d’inventer une nouvelle convention. ## Ajouter chaque nouvelle fonction à l’app et à la ligne de commande Concevez les fonctions destinées aux utilisateurs autour d’un contrat de service unique et rendez-les accessibles depuis toutes les interfaces d’interaction prises en charge. La parité entre les interfaces fait partie de l’achèvement d’une fonction ; ce n’est pas une amélioration à remettre à plus tard. Pour chaque nouvelle fonction : 1. Définissez ou mettez à jour les contrats partagés de requête, de réponse, d’erreur et d’événement. 2. Implémentez le point d’accès du service comme source unique du comportement. 3. Ajoutez l’interface graphique qui appelle ce point d’accès. 4. Ajoutez l’interface en ligne de commande qui appelle le même point d’accès. 5. Lorsque cela s’applique, fournissez des résultats de commandes lisibles par machine et des entrées par fichier pour les longues instructions. 6. Mettez à jour la liste de contrôle du changement afin d’identifier toutes les interfaces concernées. N’implémentez pas de comportements divergents dans différents clients. Si une interface n’est réellement pas applicable, expliquez pourquoi dans le journal du changement au lieu de l’omettre silencieusement. ## Créer des éléments d’écran réutilisables et faciles à utiliser pour tous Attribuez la responsabilité visuelle au plus petit composant stable tout en préservant les contrats globaux délibérés. Réutilisez les composants fondamentaux partagés avant de créer de nouvelles variantes locales. - Conservez la feuille de styles globale comme limite intentionnelle pour les importations et les variables de conception. - Placez les styles appartenant à un composant à côté de celui-ci et utilisez par défaut des modules à portée limitée. - Réservez les sélecteurs globaux aux réinitialisations, variables de conception, structures d’application, contrats de contenu partagés et points d’intégration de services tiers. - Préservez l’ordre de la cascade lors de la division des feuilles de styles et vérifiez que la spécificité ne change pas accidentellement. - Utilisez des contrôles sémantiques et des composants fondamentaux accessibles partagés pour les boutons, les libellés masqués et les comportements courants des formulaires. - Ajoutez un composant fondamental partagé uniquement si le besoin est réellement réutilisable ; conservez la disposition propre au produit dans la couche du produit. - Gardez les éléments conditionnels montés lorsque l’animation de sortie importe et modifiez leur état au moyen de classes. - Préférez les mouvements rapides en décélération, les sorties plus courtes que les entrées et une échelle initiale différente de zéro. Lorsqu’un style global voisin peut être déplacé en toute sécurité dans un changement petit et testable, déplacez-le avec le composant. Ne combinez pas une migration mécanique étendue avec des changements de comportement sans rapport. ## Vérifier les changements avec le test le plus léger qui trouve le problème Choisissez la couche de validation la plus légère capable d’observer l’exigence, puis ajoutez des vérifications plus larges uniquement lorsque le risque franchit des limites. La vérification doit correspondre à la responsabilité du changement et à son incidence sur les utilisateurs. - Pour les défauts, commencez par un test de régression réfutable et confirmez qu’il échoue avant la correction. - Limitez le test au comportement signalé ; consignez les défauts voisins comme travaux de suivi distincts. - Exécutez les protections du dépôt et les vérifications statiques, ainsi que les tests ou compilations ciblés correspondant aux paquets modifiés. - Rejouez des sessions enregistrées pour les changements concernant les analyseurs ou les flux d’événements d’agents avant de consommer de véritables appels aux fournisseurs. - Utilisez des vérifications dans le navigateur pour les interactions visibles, les animations ou les situations de concurrence que les tests unitaires ne peuvent pas prouver. - Pour les changements apportés à l’espace de travail ou aux dépendances, actualisez les liens générés et les empreintes de conditionnement exigés par le dépôt. - Comparez avec l’état de référence lorsque les ensembles de tests voisins présentent des échecs connus. Faites en sorte que l’implémentation exprime un invariant durable plutôt qu’une exception historique. N’affirmez pas qu’un élément est prêt uniquement parce que les contrôles automatisés ont réussi lorsque le critère d’acceptation exige une comparaison visuelle humaine. ## Séparer les versions de test et stables, et vérifier chaque version avant sa sortie Rendez explicites l’identité de publication, le comportement de conditionnement et les preuves de révision pour chaque canal de livraison. Ne permettez pas à des raccourcis pratiques d’effacer la séparation des canaux ou de contourner une validation fiable. - Attribuez des objectifs et des identités publiques distincts aux canaux de développement, de validation interne, de prévisualisation et de version stable. - Définissez explicitement les dépendances de promotion ; ne rendez pas un canal stable dépendant d’une étape de prévisualisation sans rapport. - Maintenez les chemins des environnements d’exécution conditionnés séparés par espace de noms et indépendants des ports temporaires. - Acheminez l’orchestration par les composants fondamentaux des paquets responsables au lieu de reconstruire les arguments de processus ou les règles d’analyse dans les appelants. - Exigez que les descriptions de changements indiquent le cas d’usage qui les motive, l’effet visible pour les utilisateurs, les interfaces concernées et les preuves de validation. - Joignez des captures d’écran montrant le point d’entrée pour les changements visibles de l’interface, et pas seulement des images isolées du composant. - Reliez les corrections de défauts à leurs tests de régression et à leurs dossiers d’incident. - Écartez du changement actuel les découvertes sans rapport, sauf si elles bloquent la correction, la sécurité, l’intégrité des données ou la compatibilité des contrats. Avant la publication, vérifiez l’artefact par le même chemin que celui qu’utiliseront les utilisateurs. N’approuvez pas les changements qui enfreignent les limites du dépôt, omettent des validations obligatoires, exposent des secrets ou risquent de corrompre des données persistantes.