Modifier un dépôt full-stack avec ses propres commandes et tests

## Lire d’abord la documentation et travailler sur une branche avec pull request Lisez les consignes générales du dépôt, la documentation des sous-systèmes, les manifestes des paquets et les implémentations voisines avant de planifier une modification. Recensez tous les volets concernés, notamment le frontend, l'API, le SDK, la CLI, la base de données, les conteneurs et la documentation. Considérez la branche par défaut protégée comme accessible en lecture seule pour le développement direct. Créez une branche au nom descriptif, effectuez des commits significatifs et ouvrez une demande de fusion pour examen. Ne réécrivez pas l'historique partagé en modifiant un commit existant et ne fusionnez pas votre propre demande lorsque le processus de travail confie cette décision à une personne chargée de l'examen. Limitez la branche au comportement demandé. Séparez les nettoyages sans rapport et préservez les modèles établis, sauf si la tâche exige une modification délibérée. ## Utiliser les commandes du dépôt et les versions figées de l’environnement Repérez les commandes documentées de développement, de formatage, d'analyse statique, de test, de migration et de démarrage avant de les exécuter. Utilisez la commande propre au paquet concerné au lieu de la remplacer par un outil appliqué à l'ensemble du dépôt. Respectez les versions épinglées de l'environnement d'exécution et les environnements existants ; une version majeure plus récente de l'environnement d'exécution n'est pas automatiquement prise en charge. Installez les dépendances uniquement lorsqu'elles manquent. Ne démarrez ni l'ensemble complet des applications, ni les conteneurs, ni les serveurs de longue durée, sauf si la tâche ou la vérification pertinente l'exige. Exécutez les outils de formatage et d'analyse statique sur les fichiers modifiés, dans les modes documentés. Commencez par un sélecteur pris en charge pour un seul test, puis étendez l'exécution uniquement à la suite directement concernée. Lorsqu'un sous-système importe un paquet SDK installé plutôt que son arborescence source, réinstallez ce SDK après l'avoir modifié et redémarrez le processus qui l'utilise. Vérifiez les ports et les prérequis nécessaires avant de lancer des processus de développement combinés. ## Garder séparés les rôles de l’interface, de l’API, des services et des migrations Définissez les responsabilités avant toute modification : - l'interface utilisateur prend en charge la présentation et l'état du client ; - l'API prend en charge la validation des requêtes et les questions de transport ; - les modules de service prennent en charge la logique métier ; - les paquets SDK et CLI prennent en charge leurs contrats publics ; - les migrations prennent en charge l'évolution de la base de données. Lisez la documentation du sous-système à modifier et examinez des fichiers existants similaires avant d'introduire un nouveau modèle. Lorsqu'une modification traverse plusieurs couches, procédez par petites étapes : définissez les types ou les schémas, implémentez la logique du service, exposez le contrat de l'API, actualisez le client, puis construisez l'interface. Installez une dépendance dans le paquet qui l'utilise. Lorsque vous ajoutez un paquet d'espace de travail, actualisez chaque manifeste de build de conteneur destiné à la production ou au développement local qui copie les métadonnées des paquets avant l'installation des dépendances. ## Suivre les règles TypeScript, Python et de la base de données Utilisez des types TypeScript stricts, évitez les types non bornés, définissez clairement les contrats des composants et de l'API, et suivez les modèles établis du dépôt pour les composants et la gestion de l'état. Préférez les composants fonctionnels et les actions d'état explicites à la transmission de propriétés à travers de nombreuses couches. Pour le code Python, fournissez des annotations de type à chaque limite de fonction, utilisez des modèles de validation pour la sérialisation et conservez la logique métier dans les services plutôt que dans les routeurs de transport. Les routeurs doivent valider les requêtes, appeler les services et mettre en forme les réponses. Suivez les règles existantes relatives aux tables et aux migrations, y compris toute interdiction de clés étrangères. Veillez à ce que les opérations de base de données restent portables entre tous les moteurs pris en charge. Pour les champs d'horodatage, utilisez la fonction auxiliaire UTC du dépôt plutôt que l'heure locale, des API obsolètes ou des conversions créées manuellement. Respectez le choix du dépôt entre le stockage dans le système de fichiers et le stockage dans la base de données. Ne transférez pas des données synchronisées du cluster vers une base de données uniquement par commodité. ## Tester chaque modification dans sa couche et sa batterie de tests Utilisez le système de test réellement configuré pour chaque sous-système. Si le frontend ne dispose d'aucun framework de tests unitaires, couvrez son comportement avec la suite de bout en bout prévue au lieu d'introduire un exécuteur non pris en charge. Placez les tests unitaires et de service du backend dans leur arborescence établie, puis exécutez la suite de la CLI après avoir modifié le code source de la CLI. Simulez le stockage externe, les fournisseurs de calcul et les interactions avec le système de fichiers afin que les tests restent rapides et déterministes. Préférez les tests directs des services pour les règles métier qui ne nécessitent pas la pile API complète. Exécutez d'abord un test ciblé, puis la suite pertinente du sous-système. Faites en sorte que les exécutions répétées restent sûres en présence de données existantes, utilisez des sélecteurs stables et accordez des délais d'attente réalistes aux travaux mis en file d'attente ou aux transitions d'état. Ne déduisez pas la réussite du seul nom d'une commande. Confirmez que les fichiers de test prévus ont été détectés et que le résultat exerce bien le comportement modifié. ## Vérifier les pages modifiées dans le navigateur et tester les API avec connexion Utilisez l'outil de navigation interactif approuvé par le dépôt pour l'inspection visuelle. Réservez les scripts automatisés de bout en bout à la suite de tests maintenue ou à une demande explicite. Lancez uniquement l'application de test nécessaire, accédez aux pages modifiées et directement liées, recueillez des preuves et corrigez les régressions visibles. Privilégiez les sélecteurs par rôle, texte exact et placeholder. Gérez les données de test répétées sans supposer que la base de données est vide. Le contenu affiché par un émulateur de terminal peut ne pas exister dans le DOM ; vérifiez-le au moyen de l'API sous-jacente lorsque cela est nécessaire. Pour les vérifications authentifiées de l'API, utilisez l'identité de test et le processus d'authentification documentés. Fournissez les en-têtes requis pour la portée du compte ou du tenant, distinguez les points de terminaison protégés de ceux qui ne le sont pas et ne placez jamais de données d'authentification réutilisables dans le code source, les journaux ou la documentation produite. ## Ajouter les dépendances avec prudence et ne pas laisser de mots de passe dans les journaux Vérifiez les manifestes des paquets avant d'ajouter des dépendances et utilisez le processus d'installation du dépôt. Maintenez actifs les hooks de formatage et d'analyse statique préalables aux commits lorsque le projet en dépend. Traitez les forçages de dépendances comme des contrôles de sécurité temporaires, et non comme des ornements permanents. Lors de la mise à niveau d'un paquet parent, vérifiez si le forçage peut être retiré, exécutez l'analyse de vulnérabilités pertinente et conservez le forçage si la dépendance résolue reste dangereuse. N'élargissez pas l'exposition des données d'authentification pendant les tests d'intégration. Simulez les fournisseurs externes lorsque leur comportement réel n'est pas l'objet du test et veillez à ce que les journaux ne contiennent ni jetons, ni mots de passe, ni identifiants personnels. ## Relire les modifications et rendre compte des preuves avant de terminer Lisez avant de planifier, réalisez la plus petite implémentation cohérente et vérifiez chaque limite concernée avant d'élargir le périmètre. Pour les modifications plus importantes, conservez une séquence explicite et facile à examiner au lieu de mélanger le travail du backend, de l'API, du client et de l'interface dans une seule étape opaque. Avant d'annoncer l'achèvement, examinez le diff et exécutez l'outil de formatage, l'analyse statique, la vérification des types, les tests, les vérifications de migration et l'inspection visuelle pertinents qu'exigent les volets modifiés. N'ajoutez pas un build complet ou une suite sans rapport uniquement pour la forme. Indiquez ce qui a changé, quelles vérifications ont été exécutées, quelles vérifications plus larges sont restées hors périmètre et tout risque résiduel. L'achèvement exige des preuves issues du comportement modifié, et non d'une simple modification réussie.