Flux de travail PR

Le contrat de gouvernance côté mainteneur pour les PRs ciblant master. Les paramètres de protection de branche, les contrats de préparation DoR/DoD et le protocole de récupération en cas d’échec sont définis ici. La revue quotidienne est détaillée dans le Guide du réviseur. Le flux côté contributeur se trouve dans Comment contribuer.

Objectifs de gouvernance

Le workflow existe pour maintenir cinq éléments vrais sous un fort volume de PR :

1. Le débit de fusion est prévisible.
2. La qualité du signal CI reste élevée, avec un retour rapide et peu de faux positifs.
3. La revue de sécurité est explicite sur les surfaces à risque.
4. Les modifications sont faciles à comprendre et à annuler.
5. Les artefacts du dépôt restent exempts de données personnelles ou sensibles.

La boucle de contrôle qui assure cela est intentionnellement structurée en couches :

• Classification d’admission : les étiquettes de chemin/taille/risque dirigent la PR vers le niveau d’analyse approprié.
• Validation déterministe : la porte de fusion repose sur des vérifications reproductibles, et non sur des commentaires subjectifs.
• Profondeur de revue fondée sur les risques : les conséquences à haut risque et les frontières de sécurité font l’objet d’une revue approfondie, tandis que les tâches à faible risque restent rapides.
• Contrat de fusion privilégiant le rollback : chaque chemin de fusion inclut un scénario de récupération concret.

L’automatisation gère les libellés de chemin/de portée, les rapports manuels de planification du tableau de bord des issues et les contrôles de la CI. Les libellés de risque, de taille, de type et de niveau de contributeur relèvent des décisions de triage des mainteneurs, sauf si un workflow maintenu en est explicitement responsable. La responsabilité finale de la fusion incombe aux mainteneurs humains et aux auteurs des PR. Une PR portant soit risk:high, soit domain:security nécessite une revue approfondie et deux approbations indépendantes de la Core Team ; une revue automatisée ne compte pas comme une approbation de la Core Team.

Contrat de tableau de projet

Le tableau Project est un tableau de planification automatisé, et non la file d’attente de révision des PR faisant autorité.

Utilisez le tableau pour évaluer la préparation des tickets, justifier le routage, regrouper les éléments de la feuille de route, gérer les dépendances, suivre l’état des bloqueurs et documenter les motifs d’exemption pour inactivité. Ces signaux évoluent suffisamment lentement pour qu’un champ du tableau ou une voie de planification reste utile.

L’automatisation actuelle est manuelle et purement informative. project-dashboard-plan.yml s’exécute sur workflow_dispatch pour un seul numéro d’issue, lit le payload de l’issue et écrit un résumé d’étape proposant la valeur Project Status existante qui correspond le mieux aux labels et à l’état actuels de l’issue. Elle n’écrit pas les champs Project, ne modifie pas les issues, n’ajoute pas de labels, ne publie pas de commentaires et ne s’exécute pas automatiquement sur les événements d’issue.

Un résumé JSON de ce découpage de planification se trouve dans project-board-contract.json. Considérez-le comme le contrat pour le planificateur en mode rapport uniquement et la future automatisation de l’actualisation du tableau, et non comme une validation pour des exécutions automatiques d’événements d’issue ou une mutation active du projet GitHub pour le moment. Les écritures ProjectV2 en production nécessitent un mappage de champs approuvé, un jeton ou une installation d’application limités au projet, ainsi qu’une vérification en lecture qui compare l’état planifié à l’état réel du projet avant que les mainteneurs ne s’y fient.

Ne répliquez pas l’état de revue natif des PR dans les voies de tableau manuelles. L’état de PR GitHub gère la décision de revue, les vérifications requises, la possibilité de fusion, les conflits, les approbations obsolètes et la disponibilité pour la fusion. Si le tableau affiche par la suite un routage de PR dérivé tel que DIRTY, BEHIND ou APPROVED, traitez-le comme une vue tableau de bord de l’état GitHub, et non comme une source de vérité distincte.

Cela permet de conserver l’utilité du tableau sans demander aux mainteneurs de le mettre à jour après chaque push, revue ou exécution CI.

L’étiquetage automatique de la taille et du risque correspond à deux questions distinctes de workflow. #9345 peut recalculer les labels de taille déterministes lors des mises à jour des PR. Son classifieur de risque reste limité à la génération de rapports jusqu’à ce que les mainteneurs examinent les éléments probants et activent séparément la modification des labels de risque. L’automatisation du risque doit respecter risk:manual jusqu’à ce qu’un mainteneur supprime cette surcharge. Le planificateur d’issue-dashboard n’applique pas et ne recalcule pas les labels de risque, de taille ou de type des PR.

Preuve de routage des tickets

Le tri des tickets reste une responsabilité partagée entre les mainteneurs. Les tickets acceptés n’ont pas besoin d’une carte de propriétaires permanente avant de pouvoir rester ouverts, et CODEOWNERS ne rend pas les propriétaires de code responsables de chaque ticket dans une zone correspondante.

Les tickets nécessitent une preuve de routage visible par les contributeurs lorsqu’un état spécial les masquerait autrement des revues de routine ou des balayages d’inactivité : status:no-stale, un état actif de suivi release/RFC/design, ou une décision de mainteneur différée. status:blocked conserve sa règle plus simple : consigner le bloqueur non résolu et réexaminer la protection contre l’inactivité une fois le bloqueur levé.

Utilisez ces significations de manière cohérente :

CODEOWNERS est un mécanisme de routage pour la revue des PR. Il peut identifier les personnes à consulter lorsqu’un problème concerne clairement un chemin, mais il ne crée pas de responsabilité sur les problèmes et ne doit pas être reproduit dans une politique obsolète comme une carte de routage privée.

La preuve d’acheminement concerne la prochaine décision, pas la responsabilité de la livraison. Un problème acheminé ne doit pas rester dans des limbes « pris en charge » ; la prochaine mise à jour visible doit rendre explicite l’un de ces résultats : affecter un développeur actif, rendre le problème prêt pour les contributeurs, l’acheminer vers un outil de suivi ou un jalon, consigner le blocage, planifier un point de décision concret pour le mainteneur, ou le clôturer/reporter avec justification.

Planifier une issue pour le tri par un mainteneur n’est valide que si l’issue indique quelle décision est requise, où cette décision sera suivie et quand elle sera réexaminée. Après cette passe de tri, remplacez le routage de tri par un implémenteur actif, une portée prête pour les contributeurs, une route vers un tracker ou un jalon, un état bloqué/différé, ou une justification de clôture.

Pour les tickets protégés, consignez à la fois la raison de l’exemption d’obsolescence et la prochaine étape de décision avant d’ajouter ou de conserver status:no-stale. Les sources de preuves visibles utiles comprennent :

• une personne assignée effectuant un travail actif ainsi qu’une note visible dans le ticket, une section de corps ou une entrée de suivi expliquant pourquoi le traitement des éléments obsolètes ne doit pas s’appliquer ;
• un commentaire de problème, une section du corps du problème ou un champ de problème public consignant la raison de l’exemption d’obsolescence et la prochaine surface de décision ;
• un champ Project public qui est visible par les lecteurs normaux des tickets et activement maintenu ;
• un tracker public lié, un jalon, une RFC ou un ticket de conception qui documente pourquoi le ticket reste ouvert et quand il devrait être réexaminé.

Les trackers de version actifs et les trackers de RFC ou de conception actifs sont des surfaces de coordination durables. Lorsque le titre, le corps, les labels ou le jalon de l’issue identifient clairement un tracker actif ou une RFC, le tracker lui-même fournit la raison d’exemption d’obsolescence et la surface de routage visible par les contributeurs ; il n’a pas besoin de commentaires répétitifs par issue. Réexaminez l’exemption lorsque le jalon se ferme, que le tracker s’écarte de l’état de version en cours, que la RFC aboutit à une décision, est remplacée ou se ferme, ou que l’issue ne représente plus une surface de décision de projet active.

Lorsqu’une étiquette de marqueur de tracker est nécessaire, utilisez type:tracker. Elle s’applique aux surfaces de coordination parentes réservées aux issues, telles que les trackers de release, les trackers de roadmap ou d’epic, les trackers RFC/design, les trackers de lots d’implémentation, les trackers de nettoyage et les trackers d’audit. Ne l’appliquez pas aux issues enfants ordinaires, aux demandes de fonctionnalités ordinaires, aux bugs, aux PR, ou aux éléments simplement liés depuis un tracker. type:tracker aide les humains et l’automatisation à trouver la surface parente ; elle ne remplace pas la raison d’exemption de stale requise, la surface de décision suivante, le jalon, l’assigné ou les critères de clôture. Si l’étiquette live n’existe pas encore, ne substituez pas roadmap, type:roadmap ou un autre alias ; créez et migrez l’étiquette canonique via un paquet d’étiquette exact séparé.

Si aucun de ces éléments n’existe et que le ticket n’est pas un suivi actif ou une RFC, le ticket peut tout de même rester ouvert pendant que le triage se poursuit, mais il ne doit pas s’appuyer sur status:no-stale comme protection permanente. Tant que l’audit d’exemption d’inactivité n’est pas en place, l’absence de motif ou de preuve de routage constitue un constat d’audit et une proposition de correction, et non un déclencheur automatique de fermeture pour inactivité.

Politique des jalons nommés

Les jalons nommés sont des cohortes de livraison finies pour des résultats délimités au sein de domaines de capacités, et non des backlogs de domaine permanents. Pour cette politique, un jalon nommé est organisé autour d’un résultat plutôt que d’une version numérotée ; Parking Lot et Icebox sont des zones de mise en attente, et non des jalons nommés. Nommez chaque nouveau jalon selon le format Domain: Bounded Outcome. Préférez RPC Client: Authentication & Authorization à un nom général et réutilisable tel que Auth. Un titre combiné occupe chacun des domaines qu’il nomme.

Traitez chaque jalon nommé ouvert comme actif. Avant d’en ouvrir un autre, les mainteneurs doivent confirmer explicitement qu’il existe une capacité suffisante de coordination et de revue pour la cohorte supplémentaire. Indiquez pourquoi la cohorte ne peut pas attendre et quel jalon actuel devrait se clôturer ensuite. Lorsque la capacité est épuisée, n’ouvrez pas d’autre jalon nommé tant que l’un d’eux n’est pas clôturé ou que le travail proposé n’est pas regroupé dans une cohorte existante. Réévaluez la capacité chaque fois que la disponibilité des mainteneurs ou la charge de revue change de manière significative.

Ne conservez pas plus d’un jalon nommé actif par domaine. Une exception explicite du mainteneur peut autoriser la poursuite en parallèle de résultats indépendants dans un même domaine lorsque la décision consigne pourquoi le coût de coordination supplémentaire est justifié.

Chaque jalon nommé doit avoir un périmètre explicite et des critères de clôture, mais une date d’échéance reste facultative. Ne laissez pas une cohorte mise en pause ouverte : réaffectez son travail inachevé et clôturez le jalon. Avant de clôturer un jalon nommé, clôturez ou réaffectez chaque ticket non terminé et ajoutez une note de clôture indiquant si le résultat a été mené à bien, annulé ou remplacé. Les jalons nommés clôturés restent clôturés. Le travail de suivi peut constituer un nouveau jalon nommé uniquement lorsqu’il existe un périmètre suffisamment cohérent pour définir un autre résultat clairement délimité. Nommez ce jalon en fonction du résultat ; ne créez pas par défaut de successeurs récurrents tels que v2, v2.1 ou similaires.

GitHub permet à un problème ou à une demande de tirage d’appartenir à un seul jalon. Le travail nécessaire pour terminer une cohorte nommée reste dans ce jalon nommé jusqu’à son achèvement, même lorsqu’il est inclus dans une version numérotée. Consignez l’inclusion dans la version dans le suivi des versions et le journal des modifications. Utilisez les jalons de versions numérotées pour les bugs urgents, la maintenance et autres travaux liés à une version qui ne relèvent pas d’une cohorte nommée.

Une fois qu’un jalon nommé est actif, limitez les nouvelles demandes aux travaux nécessaires pour achever la cohorte qu’il définit : périmètre direct, blocages, dépendances et régressions. Orientez les autres travaux selon leur objectif :

Voies de PR

Les couloirs de PR sont des attentes d’acheminement, pas une nouvelle famille d’étiquettes obligatoires. Utilisez-les pour décider du niveau de profondeur de revue, de séquencement et d’attention des mainteneurs dont une PR a besoin. CODEOWNERS, l’état de revue natif de GitHub, la CI, les étiquettes, les tickets liés et les mots-clés de relation explicites continuent de porter les véritables données d’acheminement.

Ne créez pas de tableau PR manuel distinct pour ces lanes, sauf si l’état GitHub natif et CODEOWNERS ne répondent plus à la question du routage. Vérifiez l’état de fusion GitHub natif avant la revue normale de lane : DIRTY signifie qu’il faut d’abord résoudre les conflits ; BEHIND seul relève de la maintenance de la fusionnabilité, pas d’un blocage côté auteur.

Paramètres requis du dépôt

Protection de la branche sur master :

• Exiger les vérifications d’état avant la fusion.
• Vérifier la condition CI Required Gate.
• Exiger des revues de pull request avant la fusion.
• Exiger une revue CODEOWNERS pour les chemins protégés. .github/** (y compris .github/workflows/**) appartient aux mainteneurs listés dans .github/CODEOWNERS, donc les modifications de workflows nécessitent la revue d’un mainteneur propriétaire.
• Limiter le contournement des branches / ensembles de règles aux seuls propriétaires de l’organisation.
• Rejeter les approbations obsolètes lorsque de nouveaux commits sont poussés.
• Restreindre le force-push.
• Toutes les PR des contributeurs ciblent directement master.

Définition de Prêt (DoR)

Avant de demander une revue, la PR contient tout ce qui suit :

• Modèle de PR entièrement rempli.
• Limite du périmètre explicite (ce qui a changé / ce qui n’a pas changé).
• Preuves de validation jointes, sortie de commande réelle, et non « la CI vérifiera ».
• Champs de sécurité et confidentialité, de compatibilité et (pour les chemins à risque) de restauration complétés.
• Règles de confidentialité et d’hygiène des données respectées, formulation de test neutre et limitée au projet. Voir Confidentialité.
• Une formulation de type identitaire, lorsqu’elle est inévitable, utilise les étiquettes ZeroClaw / propres au projet.

Définition de fait (DoD)

Avant la fusion :

• CI Required Gate est vert.
• Les réviseurs requis ont approuvé (y compris les chemins CODEOWNERS) ; une PR portant risk:high ou domain:security a obtenu deux approbations indépendantes de la Core Team.
• Les libellés de risque correspondent au diff réel et à la conséquence plutôt qu’à l’emplacement général du composant. Voir Libellés.
• L’impact de la migration / compatibilité est documenté.
• Le chemin de rollback est concret et rapide.

Liste de vérification du mainteneur pour la fusion

Chaque fusion :

• Le périmètre est clair et compréhensible.
• Le pipeline CI est vert.
• Les vérifications de qualité des docs sont vertes lorsque les docs ont changé.
• Les champs de sécurité et de confidentialité sont complets ; les preuves sont masquées/anonymisées.
• Une PR portant risk:high ou domain:security dispose de deux approbations indépendantes de la Core Team ; la revue automatisée ne compte pas.
• Les notes du workflow de l’agent sont suffisantes pour la reproductibilité (si assisté par l’IA).
• Le plan de rollback est explicite.
• Le titre de la validation suit la convention Conventional Commits.

Squash-merge avec l’historique complet des commits préservé dans le corps. Le skill squash-merge produit à la fois le badge violet Merged et le corps formaté selon les conventional commits, voir Skills pour l’invocation.

Politique de contribution des IA / Agents

Les PRs assistées par l’IA sont les bienvenues. La revue peut également être assistée par un agent.

Requis :

1. Résumé de la PR avec une limite de portée.
2. Preuve explicite du test / validation.
3. Notes d’impact sur la sécurité et de rollback pour les modifications risquées.

Recommandé :

1. Notes d’outil / de flux de travail lorsque l’automatisation a influencé de manière significative le changement.
2. Extraits de prompt / plan optionnels pour la reproductibilité.

Nous ne demandons pas aux contributeurs de quantifier la propriété des lignes entre l’IA et les humains. Le diff et les preuves de validation assurent cette charge.

Pour les PRs très dépendantes de l’IA, les relecteurs se concentrent sur :

• Compatibilité des contrats.
• Limites de sécurité.
• Gestion des erreurs.
• Régressions de performance et de mémoire.
• Si l’auteur peut répondre aux questions sur le comportement et l’impact (compréhension de l’intention).

Examiner le SLA et la discipline de file d’attente

• Premier objectif de triage par le mainteneur principal : dans les 48 heures.
• Les PRs bloquées reçoivent un seul commentaire avec une liste d’actions à effectuer, et non une série de revues partielles.
• status:no-stale est réservé aux travaux acceptés ou ayant une longue durée de vie, avec une raison d’exemption d’obsolescence enregistrée et une preuve de routage visible par les contributeurs lorsque le problème n’est pas déjà protégé par une autre exclusion d’obsolescence. Les trackers de version actifs et les trackers de RFC ou de conception actifs peuvent utiliser le tracker lui-même comme raison visible et surface de routage tant qu’ils restent actifs. Les exemptions existantes auxquelles manquent ces éléments constituent des constats d’audit jusqu’à ce que le paquet de réparation d’exemption d’obsolescence soit livré.

Pour les travaux empilés, exigez un Depends on #... explicite afin que l’ordre de révision soit déterministe.

Appliquez concrètement cet ordre déterministe : donnez la priorité au parent et examinez-le avant ses enfants ; lorsqu’un parent ne peut pas encore être examiné, reportez l’examen approfondi de l’enfant, sauf si une portion indépendante et délimitée bénéficie d’un examen anticipé ; une fois le parent intégré, actualisez et revalidez l’enfant. Le fait qu’un parent puisse être examiné ne rend pas à jour les éléments probants précédemment recueillis pour l’enfant.

Pour générer un instantané, uniquement à des fins de rapport, des files d’attente GitHub en temps réel, exécutez python3 scripts/github/pr_review_queue.py --queue all --older-than-days 7 --format table. Les valeurs de --queue sont near-ready, maintainer, second-core, author-action, stacked, mine et all ; --format accepte table, json ou links. near-ready restreint la file des mainteneurs aux PR dont le statut de recherche GitHub est réussi, afin que les mainteneurs puissent commencer par les candidats qui pourraient nécessiter moins de travail avant la fusion ; cela ne permet pas d’établir que les PR peuvent être fusionnées ni que les approbations sont suffisantes. all exécute indépendamment les files communes, de sorte qu’une même PR peut apparaître dans plusieurs files ; ajoutez --author LOGIN pour inclure la file mine. La recherche GitHub fournit les listes de candidats. Seule la file author-action lit les détails de la chronologie pour estimer l’ancienneté des demandes restées sans réponse, et seule la file second-core lit les avis pour trouver une approbation Core sur la révision actuelle. La commande n’écrit jamais l’état des files d’attente et n’apporte aucune modification à GitHub ; elle signale les détails manquants ou ambigus comme inconnus. Il s’agit d’un outil d’aide à la sélection des tâches, et non d’une preuve qu’une PR est prête à être fusionnée.

Pour les remplacements, exigez explicitement Supersedes #.... Consultez Les PRs de remplacement pour les règles d’attribution et de modèle.

La gestion de la file d’attente côté relecteur, l’ordre d’élagage du backlog, le traitement des éléments obsolètes, l’hygiène des labels, sont décrits dans le Reviewer Playbook.

Règles de sécurité et de stabilité

Examinez attentivement ces chemins, car ils contiennent souvent des comportements liés aux limites :

• crates/zeroclaw-runtime/ (y compris src/security/)
• crates/zeroclaw-gateway/ (entrée, authentification, appariement)
• crates/zeroclaw-tools/ (tout ce qui a une capacité d’exécution)
• .github/workflows/ et le pipeline de publication

L’emplacement du chemin à lui seul ne suffit pas à sélectionner risk:high. Classez le diff réel et ses conséquences sous Labels → Étiquettes de risque. Une frontière de confiance, d’informations d’identification, de compatibilité, de gouvernance, d’autorité de mise en production ou de sécurité transverse fait l’objet d’une revue approfondie lorsque la PR porte risk:high ou domain:security.

Les limites d’accès au système de fichiers ainsi que le comportement réseau ou d’authentification au sein de ces crates méritent une attention particulière, même lorsque le diff est réduit.

Minimum requis pour les PR risk:high ou domain:security : déclaration de menace ou de risque, notes d’atténuation, étapes de restauration et deux approbations indépendantes de la Core Team.

Recommandé pour les PR risk:high ou domain:security : un test ciblé démontrant le comportement aux limites, ainsi qu’un scénario explicite de mode de défaillance avec la dégradation attendue.

Pour les contributions assistées par un agent qui franchissent ces limites, les réviseurs vérifient également que l’auteur est capable d’expliquer le comportement à l’exécution et le rayon d’impact, et pas seulement de coller la sortie de validation.

Récupération après échec

Si une PR fusionnée provoque des régressions :

1. Revert sur master immédiatement.
2. Ouvrez un ticket de suivi avec une analyse de la cause racine.
3. Réintroduisez la correction uniquement avec des tests de régression couvrant le mode de défaillance.

Privilégiez une restauration rapide de la qualité de service plutôt qu’une correction parfaite mais retardée.

Ce que cette page ne couvre PAS

• Mécanique quotidienne de revue : voir Reviewer Playbook et PR Review Protocol.
• Seuils et définitions des libellés : voir Labels.
• Règles de confidentialité et de données personnelles (PII) : voir Privacy.
• Attribution et modèles de remplacement : voir PR de remplacement.
• Inventaire et triage des workflows CI : voir CI & Actions.
• Procédure de publication : voir le Release Runbook.