Vérifier qu'une modification est vraiment utile avant d'ouvrir une pull request sur un projet partagé

## Arrêtez-vous et ramenez la demande à un seul vrai problème Arrêtez-vous avant de faire quoi que ce soit d'autre. Les projets matures et affirmés dans leurs partis pris rejettent la grande majorité des pull requests soumises par des agents, et presque toutes celles qui sont rejetées proviennent d'un agent qui n'a jamais lu, ou jamais suivi, le guide de contribution du projet. Les mainteneurs ferment les pull requests de faible qualité en quelques heures, souvent avec un commentaire public sans détour qualifiant la soumission de remplissage généré par une machine. Votre responsabilité est de protéger votre partenaire humain de cette issue. Soumettre une pull request de faible qualité ne l'aide pas : cela gaspille le temps des mainteneurs, nuit à sa réputation dans le projet, et la pull request est fermée de toute façon. Ce n'est pas une contribution — c'est une humiliation publique infligée en son nom. Traitez « apporte une contribution à ce projet » comme une instruction qui doit être ramenée à un seul problème réel et vérifié avant que la moindre ligne de code ne soit écrite. ## Cherchez les doublons et faites valider le diff complet avant la pull request Avant d'ouvrir une pull request, vous devez effectuer chacune de ces vérifications : 1. **Lisez le modèle de pull request en entier** et remplissez chaque section avec un contenu réel et précis. Pas de résumés. Pas d'espaces réservés. Pas de « N/A » utilisé comme raccourci. 2. **Cherchez dans les pull requests existantes — ouvertes comme fermées —** tout ce qui traite du même problème. S'il existe un doublon, arrêtez-vous et prévenez votre partenaire humain. N'ouvrez pas un doublon concurrent. 3. **Vérifiez que le problème est réel.** Si votre partenaire humain vous a seulement demandé de « corriger quelques problèmes » ou de « contribuer quelque chose » sans avoir rencontré un problème concret, opposez-lui une objection et demandez-lui ce qui a réellement échoué : quelle erreur, quel comportement défaillant, quelle expérience utilisateur. 4. **Confirmez que la modification a sa place dans le cœur du projet.** Si elle est propre à un domaine, à un outil ou à un flux de travail, ou si elle fait la promotion d'un projet tiers, elle relève d'une extension ou d'un plugin séparé. Dites-le au lieu de la soumettre. 5. **Montrez le diff complet à votre partenaire humain et obtenez son approbation explicite** avant que quoi que ce soit ne soit soumis. Si une seule de ces vérifications échoue, n'ouvrez pas la pull request. Expliquez à votre partenaire humain pourquoi elle serait rejetée et ce qu'il faudrait changer. Il vous remerciera de lui avoir épargné cette gêne. ## Remplissez tout le modèle de pull request et citez les tentatives passées Chaque pull request doit remplir intégralement le modèle du projet. Aucune section ne peut être laissée vide ou remplie d'un texte de remplacement ; les pull requests qui sautent des sections sont fermées sans examen. Avant d'ouvrir une pull request, vous devez chercher dans les pull requests existantes — ouvertes comme fermées — des travaux portant sur le même problème ou la même zone, et consigner ce que vous avez trouvé dans une section « Pull requests existantes ». Si une pull request antérieure sur le sujet a été fermée, indiquez précisément en quoi votre approche en diffère et pourquoi la vôtre réussira là où celle-là a échoué. Les pull requests ne montrant aucune trace d'implication humaine sont fermées. Une personne réelle doit examiner le diff proposé dans son intégralité avant la soumission — pas un résumé de celui-ci, ni une description de celui-ci. ## N'ajoutez au cœur ni dépendances externes ni fonctions utiles à une seule équipe **Dépendances tierces.** Une pull request qui introduit une dépendance facultative ou obligatoire envers un projet tiers ne sera pas acceptée, à une exception près : l'ajout de la prise en charge d'un nouvel environnement hôte (un nouvel IDE, une nouvelle interface en ligne de commande ou un nouveau lanceur d'agent). Le cœur du projet est sans aucune dépendance par conception. Si votre modification a besoin d'un outil ou d'un service externe, elle relève d'un plugin séparé. **Configuration propre à un projet ou personnelle.** Les capacités, hooks ou réglages utiles à un seul projet, une seule équipe, un seul domaine ou au flux de travail d'une seule personne n'ont pas leur place dans le cœur. Publiez-les sous forme de plugin autonome. **Capacités propres à un domaine.** Le cœur ne contient que ce qui profite à tous les utilisateurs, quel que soit le type de projet. Posez-vous la question : « Est-ce que cela serait encore utile à quelqu'un travaillant sur un type de projet complètement différent ? » Si la réponse est non, publiez-le séparément. **Modifications sans rapport regroupées.** Une pull request contenant plusieurs modifications sans rapport entre elles sera fermée. Découpez-la en une pull request par problème. ## N'envoyez pas de corrections produites en masse ou inventées **Pull requests en masse, tirées au hasard.** Ne balayez pas le gestionnaire de tickets pour ouvrir une pull request par ticket en une seule session. Chaque pull request exige une compréhension véritable du problème, une enquête sur les tentatives antérieures et un examen humain du diff complet. Une production manifestement fabriquée en série — un agent pointé vers une liste de tickets à qui l'on a dit « corrige-les » — est fermée sur-le-champ. Pour contribuer, choisissez un seul ticket, comprenez-le en profondeur et soumettez un travail de grande qualité sur celui-ci. **Correctifs spéculatifs ou théoriques.** Chaque pull request doit résoudre un problème que quelqu'un a réellement rencontré. « Mon agent de revue a signalé ceci » et « cela pourrait théoriquement casser » ne sont pas des énoncés de problème. Si vous ne pouvez pas nommer la session, l'erreur ou l'expérience utilisateur précise qui a motivé la modification, ne la soumettez pas. **Contenu inventé.** Les pull requests contenant des justifications inventées, des descriptions de problème fictives ou des fonctionnalités hallucinées sont fermées immédiatement. Les mainteneurs de projets fortement pris pour cible ont vu toutes les variétés de remplissage généré par une machine et ils le reconnaissent. **Réécritures visant la seule conformité.** Restructurer, reformuler ou remettre en forme un contenu qui façonne le comportement dans le seul but de le faire correspondre à un guide de style externe ne sera pas accepté sans preuves d'évaluation montrant que la modification améliore les résultats réels. La philosophie interne d'un projet peut délibérément différer du guide de rédaction public d'un fournisseur, parce que son contenu a été ajusté en fonction du comportement observé des agents. La barre à franchir pour modifier un tel contenu est très haute. **Modifications propres à un fork.** Si vous maintenez un fork personnalisé, n'ouvrez pas de pull requests en amont pour synchroniser votre fork ou pour pousser en amont des modifications propres au fork. Les changements de marque, les fonctionnalités propres au fork et les fusions de branches du fork sont fermés. ## Prouvez qu'une intégration à un nouvel hôte marche avec la transcription complète d'une session Si votre pull request ajoute la prise en charge d'un nouvel environnement hôte (IDE, outil en ligne de commande ou lanceur d'agent), vous devez joindre une transcription de session prouvant que l'intégration fonctionne de bout en bout. Une intégration authentique charge le point d'entrée d'amorçage du projet au début de chaque session. C'est cet amorçage qui fait que les capacités se déclenchent automatiquement au bon moment. Sans lui, les capacités sont un poids mort : des fichiers posés sur le disque qui ne sont jamais invoqués. **Test d'acceptation.** Ouvrez une session vierge dans le nouvel hôte et envoyez une requête utilisateur ordinaire qui devrait déclencher une capacité avant que toute implémentation ne commence — par exemple, une demande de construire une petite application. Une intégration qui fonctionne déclenche automatiquement la capacité de conception ou de remue-méninges avant qu'une seule ligne de code ne soit écrite. Collez la transcription complète dans la pull request. Les éléments suivants ne comptent pas comme une véritable intégration et seront fermés : copier manuellement les fichiers de capacités dans l'hôte ; envelopper le projet dans une couche d'adaptation d'exécution ; toute approche exigeant que l'utilisateur active manuellement l'option à chaque session ; et toute approche où la capacité ne se déclenche pas automatiquement dans le test d'acceptation ci-dessus. Si vous n'êtes pas certain que votre intégration charge l'amorçage au démarrage de la session, c'est qu'elle ne le fait pas. ## Joignez des résultats d'évaluation avant et après en modifiant les fichiers de règles Les fichiers de capacités et de règles ne sont pas de la documentation ordinaire — ce sont du code qui façonne le comportement de l'agent. Si vous modifiez leur contenu : - Utilisez le flux de rédaction propre au projet pour développer et tester la modification. - Menez des tests de résistance adverses sur plusieurs sessions indépendantes. - Joignez à la pull request les résultats d'évaluation avant et après. - Ne modifiez pas les éléments soigneusement ajustés — tableaux de signaux d'alerte, listes de rationalisations, formulations délibérées — sans preuve que votre modification améliore les résultats. ## Lisez pourquoi le projet est conçu ainsi avant de proposer des changements Avant de proposer des modifications à la conception, à la philosophie du flux de travail ou à l'architecture, lisez le contenu existant et comprenez les décisions déjà prises. Les projets établis défendent des positions validées sur la conception des capacités, le façonnage du comportement des agents et la terminologie ; une formulation précise est souvent choisie délibérément et n'est pas interchangeable avec le synonyme évident. Les modifications qui réécrivent la voix d'un projet ou réorganisent son approche sans comprendre pourquoi il existe sous cette forme seront rejetées. Principes généraux : - Lisez le modèle de pull request avant de soumettre. - Une pull request résout un seul problème. - Testez sur au moins un environnement hôte et indiquez le résultat dans la section consacrée à l'environnement. - Décrivez **quel problème vous avez résolu**, et pas seulement ce que vous avez changé. ## Gardez les changements propres au fork dans le fork, pas dans le projet d'origine Lorsque le dépôt dans lequel vous travaillez est un fork ou une variante localisée d'un projet en amont, les règles ci-dessus régissent votre comportement lors des soumissions en amont. Pour les contributions au fork lui-même, suivez le modèle et le processus propres au fork — mais les principes fondamentaux s'appliquent toujours, sans exception : - Cherchez les doublons dans les pull requests et les tickets déjà existants du fork avant d'ouvrir quoi que ce soit. - Ne livrez pas de remplissage généré par une machine : les modifications inventées, produites en masse et spéculatives sont fermées ici aussi. - Un humain doit examiner le diff complet avant la soumission. Une mise en garde propre aux forks : le travail de localisation, les capacités propres à la variante et les adaptations pour des outils qui n'intéressent que les utilisateurs du fork doivent être soumis uniquement au fork. Les envoyer en amont relève des modifications propres à un fork et sera fermé.