Apporter des changements petits et compatibles dans un projet Java découpé en modules

## Vérifier les règles de build, de formatage et de CI avant de modifier Considérez les directives du dépôt, la configuration de compilation, les règles de formatage et les contrôles d'intégration continue comme des contrats exécutables. Lisez les instructions applicables avant toute modification et déterminez quelles règles sont imposées mécaniquement. - Repérez le script de compilation officiel, l'outil de formatage, les contrôles statiques, les commandes de test et la politique de contribution. - Avant de modifier le code, remontez jusqu'au module responsable et à ses dépendances. - Préférez les utilitaires et modèles établis du projet aux solutions de remplacement qui ne sont pratiques que localement. - Distinguez la compatibilité du code source, les exigences des outils de compilation, la prise en charge de l'environnement d'exécution et le comportement de la distribution. - Ne désactivez pas un contrôle qualité dans le seul but de faire accepter une modification. Utilisez la plus petite entrée faisant autorité qui commande le comportement demandé. ## Garder le code compatible avec la version de Java et les dépendances déclarées Une compilation peut nécessiter une chaîne d'outils récente alors que son code source reste compatible avec un ancien environnement d'exécution. Compilez et testez selon le niveau de source déclaré ; ne supposez pas qu'un environnement local récent autorise de nouvelles fonctions du langage ou de nouvelles API de bibliothèque. - Remplacez les API pratiques non prises en charge par des équivalents compatibles. - Si nécessaire, utilisez les espaces de noms des dépendances relocalisées ou ombrées du dépôt. - Préférez les utilitaires propres au projet pour la validation, la sérialisation, les collections, les fichiers, les Future et le temps. - Évitez les importations directes de bibliothèques tierces lorsque la distribution isole ces bibliothèques. - Avant d'ajouter une dépendance, examinez la compatibilité, les licences, la mise en paquet et les effets transitifs. Vérifiez la compatibilité avec la cible de compilation désignée par le dépôt, et non au moyen de la seule compilation locale. ## Utiliser des factories, des builders et des résultats immuables dans les API publiques Marquez les API selon la stabilité prévue : les contrats publics stables, les contrats publics en évolution et les surfaces d'implémentation internes doivent rester distincts. - Faites en sorte que les fabriques renvoient des interfaces et dissimulez la construction derrière des constructeurs privés ou des méthodes de création statiques. - Utilisez des builders pour les configurations en plusieurs étapes, avec des méthodes fluides et un unique point de construction validé. - Gardez les objets de résultat immuables, avec un état déclaré final, sans setters et avec des implémentations complètes de l'égalité, du hachage et de la représentation textuelle. - Fournissez des interfaces génériques et typées lorsque les appelants ont besoin des deux formes sans conversion de type dangereuse. - Documentez les exigences de sécurité des threads sur les types publics. La modification d'un contrat public exige une analyse de compatibilité et la voie de gestion des versions appropriée. ## Garder les dépendances entre modules dans un seul sens Cartographiez le graphe des modules avant l'implémentation. Les modules fondamentaux doivent contenir les types et interfaces partagés ; les couches de protocole ou de transport se construisent au-dessus ; les modules homologues du client et du serveur ne doivent pas dépendre l'un de l'autre ; les intégrations se placent au-dessus des couches inférieures stables. - Définissez les interfaces partagées dans le module approprié de plus bas niveau, et placez leurs implémentations au-dessus. - Empêchez les connecteurs et les intégrations facultatives d'introduire leurs dépendances dans le noyau. - Évitez les dépendances circulaires et les importations entre modules homologues motivées par la seule commodité. - Reproduisez dans les tests la structure des paquets du code de production. - Placez le code généré, les ressources de distribution, les générateurs de documentation et les utilitaires de test dans les modules qui leur sont réservés. Lorsqu'une fonction traverse des frontières, modifiez explicitement chaque couche responsable au lieu de contourner l'architecture. ## Distinguer les types d’erreur et protéger l’état partagé par des verrous Validez les entrées aux frontières de l'API avec les utilitaires de précondition standard du projet et des messages indiquant la marche à suivre. Préservez la hiérarchie des exceptions afin que les appelants puissent distinguer les erreurs d'utilisation, les échecs pouvant faire l'objet d'une nouvelle tentative et les échecs internes non contrôlés. - Propagez les échecs asynchrones au moyen des utilitaires Future et des gestionnaires d'erreurs établis. - Composez les traitements asynchrones au lieu de les bloquer sans raison documentée. - Protégez l'état mutable partagé par des verrous explicites et documentez les champs protégés. - N'utilisez des mécanismes de visibilité que lorsque l'accès en dehors du verrou les exige. - Fermez les ressources au moyen d'une gestion structurée des ressources. - Rendez les opérations de fermeture idempotentes lorsque le nettoyage peut être répété. Ne masquez pas les échecs contrôlés et ne regroupez pas les erreurs permanentes et celles pouvant faire l'objet d'une nouvelle tentative dans une seule exception indifférenciée. ## Garder compatibles les clés de configuration et les schémas de messages Le cas échéant, définissez les configurations à l'aide de builders typés comportant des valeurs par défaut, des descriptions, des valeurs facultatives et une gestion des clés obsolètes. Utilisez des clés hiérarchiques et cohérentes, et accédez aux valeurs par l'intermédiaire de l'abstraction de configuration du dépôt. Pour la sérialisation et les messages distants : - conservez le schéma et la version de protocole déclarés ; - utilisez uniquement les formes de champ prises en charge par cette version ; - régénérez le code avec le générateur officiel après toute modification du schéma ; - conservez l'immuabilité des messages de transport et marquez en conséquence les types internes de transport ; - représentez explicitement les champs facultatifs ; - ne modifiez jamais les fichiers générés lorsqu'ils relèvent d'un flux de génération. Mettez à jour les tests de compatibilité et la documentation générée chaque fois qu'un contrat de configuration ou de transport change. ## Écrire des tests unitaires et d’intégration avec les outils de test du projet Utilisez le cadre de test, la bibliothèque d'assertions, les conventions de nommage, les extensions et les fixtures de base choisis par le dépôt. N'y mêlez pas d'autres assertions ou mécanismes de délai d'attente qui entrent en conflit avec l'infrastructure globale de test. - Écrivez des tests unitaires ciblés pour les comportements locaux et des tests d'intégration pour les contrats entre composants. - Utilisez des noms de test descriptifs qui indiquent le comportement évalué. - Vérifiez à la fois les résultats réussis et les échecs attendus. - Réutilisez les fixtures prises en charge pour les grappes, le stockage ou les services au lieu de créer une infrastructure parallèle. - Exécutez d'abord le test concerné le plus restreint, puis la suite directement touchée. - Confirmez que le test échoue pour la raison prévue avant de vous en servir pour prouver une correction. Testez par l'intermédiaire du comportement public lorsqu'un détail d'implémentation interne ne fait pas partie du contrat. ## Compiler et vérifier via le wrapper de build du projet Utilisez le script du dépôt pour la compilation, le formatage, l'analyse statique, les contrôles de licence, la génération de code et les tests. Les commandes officielles peuvent préparer des ressources générées ou imposer des exigences de compatibilité que l'appel direct des outils ne prend pas en compte. - Compilez avec la chaîne d'outils documentée tout en conservant la cible de code source déclarée. - Démarrez les dépendances et composants des services locaux dans l'ordre documenté. - Modifiez uniquement les fichiers et valeurs de configuration pris en charge. - Exécutez le formatage avant les contrôles statiques. - Exécutez les suites concernées avant une vérification plus large. - Utilisez le profil de couverture lorsque la modification peut changer le comportement testé. Comprenez les étapes de l'intégration continue et reproduisez localement l'étape pertinente avant d'annoncer la fin du travail. ## Suivre le formateur et ne pas mêler de changements sans rapport au diff Respectez l'ordre imposé des importations et des modificateurs, la syntaxe des tableaux, les règles d'accolades, la politique des espaces blancs et les conventions de nommage. Laissez l'outil de formatage officiel régler le style mécanique. - Évitez les importations avec caractère générique ainsi que les marqueurs de commentaire ou les étiquettes d'attribution interdits par le dépôt. - Gardez les API public et protected documentées lorsque le projet l'exige. - Respectez les limites de taille des fichiers en extrayant des responsabilités cohérentes, et non en condensant le code au détriment de sa lisibilité. - Mettez la documentation à jour lorsque les commandes, la configuration, la compatibilité ou le comportement public changent. - Examinez la différence finale pour détecter les réécritures sans rapport, les modifications accidentelles de fichiers générés, les secrets et les nettoyages inachevés. Ne combinez pas une modification de comportement ciblée avec une refactorisation sans rapport. ## Publier les changements par des branches de revue, jamais par force-push Travaillez sur une branche autorisée et vérifiez chaque dépôt distant avant d'effectuer un push. Protégez les branches en amont ou partagées ; publiez les modifications par la voie de revue du projet au lieu d'écrire directement dans des cibles protégées. - Effectuez un rebase ou une mise à jour à partir de la branche de base officielle en suivant le flux documenté. - Rédigez un objet de commit concis et limité au composant, puis expliquez la motivation dans le corps si nécessaire. - Examinez la différence complète de la branche avant sa publication. - Exécutez le formatage, les contrôles statiques et de licence, ainsi que les tests concernés. - Ajoutez un résumé simple et un plan de test à la demande de revue. - Signalez les modifications réalisées avec assistance afin qu'elles soient examinées par une personne lorsque la politique de contribution l'exige. N'effectuez jamais de force-push sur une branche partagée et n'utilisez pas d'opérations destructrices sur l'historique sans autorisation explicite. ## Demander avant un travail large ou destructeur, comme une nouvelle dépendance ou un reset Procédez de façon autonome aux lectures délimitées, compilations locales, tests, formatages, diagnostics et corrections qui respectent les règles existantes. Demandez une autorisation avant tout travail étendu ou lourd de conséquences, notamment les refactorisations entre modules, les nouvelles dépendances, les migrations de schéma, les modifications du système de compilation, celles de l'intégration continue ou les opérations destructrices. Sans autorisation explicite, ne faites jamais ce qui suit : - inclure des identifiants d'accès ou des valeurs sensibles dans un commit ; - effectuer un push directement vers une cible protégée en amont ; - effectuer un force-push sur l'historique partagé ou supprimer des branches ; - exécuter un hard reset ou un nettoyage destructeur ; - contourner les hooks, les contrôles statiques ou les règles de formatage ; - modifier les résultats générés au lieu de leurs fichiers sources ; - affaiblir les contrôles qualité afin d'obtenir un résultat accepté. Avant de terminer, vérifiez les tests, le formatage, les contrôles statiques, les en-têtes requis et la différence prévue dans son intégralité. Si la portée ou la réversibilité est incertaine, arrêtez-vous et expliquez la décision nécessaire.