Guide du réviseur

Le modèle opérationnel pour la revue des PRs et le tri des problèmes. Conçu pour maintenir une qualité de revue élevée même sous une forte charge ; il dirige les éléments par niveau de risque afin que les chemins à haut risque reçoivent l’attention nécessaire sans entraver chaque petit changement par les mêmes étapes.

Pour la séquence de récupération réelle et les mécanismes de verdict de la revue de code, consultez le Protocole de revue de PR. Cette page est le modèle opérationnel ; le protocole est la procédure.

Chemins rapides

Utilisez cette section pour router une revue avant de lire plus en détail. Chaque ligne renvoie à la section qui développe le sujet.

Utilisez les voies de PR pour les attentes de routage ; utilisez la matrice des risques de ce guide pour la profondeur de revue.

Matrice de profondeur de révision

domain:security reste indépendant de risk:* : utilisez-le pour une véritable frontière de sécurité ou de confiance, et non simplement parce que le composant modifié est lié à la sécurité. L’un ou l’autre libellé déclenche le même processus de revue approfondie et d’approbation par deux membres indépendants de la Core Team. Une revue automatisée ne compte pas comme une approbation de la Core Team.

En cas d’incertitude, classez dans la catégorie supérieure et demandez à un mainteneur de trancher le cas limite avant la fusion.

Les libellés de risque sont actuellement gérés manuellement. #9345 maintient tout futur classifieur de risque en mode signalement uniquement jusqu’à ce que les mainteneurs activent séparément les modifications. Suivez le contrat d’automatisation des libellés : risk:manual bloque le remplacement automatisé du risque lorsqu’une correction effectuée par un mainteneur doit persister, mais il ne réduit jamais les exigences de revue ou d’approbation.

Les labels sont des métadonnées de mainteneur. Si le label correct est évident et que vous disposez des autorisations nécessaires, corrigez-le vous-même avant de finaliser la revue. Ne demandez à l’auteur que lorsque le choix du bon label est ambigu ou qu’aucune personne disposant des autorisations sur les labels n’est disponible.

Flux de travail standard

Prise en charge de cinq minutes

Pour chaque nouveau PR, avant de lire le code :

1. Vérifiez que le modèle de PR est complet : résumé, preuves de validation, sécurité et confidentialité, compatibilité, retour arrière (pour les niveaux moyen/élevé).
2. Vérifiez que les étiquettes sont présentes et plausibles : size:*, risk:*, étiquettes de portée, niveau de contributeur le cas échéant.
3. Confirmer l’état du signal CI Required Gate.
4. Confirmer que le périmètre est une préoccupation. Les PRs méga avec des fonctionnalités mixtes sont renvoyées pour un split, sauf si le mélange est explicitement justifié.
5. Confirmez les règles de confidentialité / hygiène des données. Consultez Privacy pour le règlement complet.
6. Si la PR modifie la présentation visuelle, vérifiez que l’auteur a testé l’interface réellement prise en charge et fourni des captures d’écran respectueuses de la confidentialité à des dimensions représentatives. Signaler que le test de fumée n’a pas été effectué documente la lacune, mais ne permet pas de satisfaire à cette exigence.

Si l’une des vérifications d’admission échoue, laissez un seul commentaire avec une liste de contrôle actionnable et arrêtez-vous. N’effectuez pas de revue approfondie d’une PR qui n’a pas passé l’admission : les allers-retours coûtent moins cher à ce niveau qu’après que le diff a été analysé en détail.

Liste de contrôle rapide (chaque PR)

• La limite du périmètre est explicite et crédible.
• Les modifications de comportement sont vérifiées par rapport au contrat de contrôle : documentation d’architecture, modules « source de vérité », limites des traits, tests existants, structure de l’API publique, commentaires du code source, ou décisions explicites des mainteneurs.
• La provenance du corps de PR est vraie. Des RFCs, audits, issues, PRs, chemins, artefacts générés ou constats de suivi cités existent et soutiennent l’affirmation.
• Les preuves de validation nomment les contrôles sur lesquels on s’appuie et pourquoi ils couvrent le comportement modifié.
• Les affirmations directement observables par l’utilisateur identifient la frontière utilisateur et fournissent la preuve crédible minimale qui l’atteint ; utilisez la preuve de frontière utilisateur lorsque les preuves unitaires, avec mocks, de compilation ou de CI générique s’arrêtent en deçà.
• Les changements de présentation visuelle incluent des preuves issues de l’interface réelle provenant d’une révision identifiable, ainsi que des captures d’écran avec suffisamment de contexte de mise en page pour évaluer le résultat. Les assertions sur les chaînes, les instantanés limités aux composants et les tests du moteur de rendu au niveau des utilitaires ne peuvent pas remplacer cette preuve. Les affirmations concernant les interactions et les transitions indiquent également l’action de l’utilisateur et le résultat observé.
• La duplication de Cargo local n’est pas requise lorsque le CI requis couvre la même branche, la même cible et le même ensemble de fonctionnalités. Demandez une validation supplémentaire uniquement lorsqu’elle correspond à un écart identifié dans le jalon requis, tels que les tests macOS/Windows, Clippy multiplateforme, la couverture desktop, les builds pour la cible de release, le CI obsolète ou le CI indisponible.
• Les modifications du comportement visibles par l’utilisateur sont documentées.
• L’auteur démontre une compréhension du comportement et de l’impact (en particulier pour les PR assistées par l’IA).
• Le chemin de restauration (rollback) est concret ; « revert » n’est pas concret.
• La compatibilité et l’impact de la migration sont clairs.
• Les modifications du MSRV, de la toolchain verrouillée ou d’autres seuils minimaux de version sont signalées comme ayant un impact sur la compatibilité : la PR indique qui doit effectuer une mise à jour, les seuils de base de la CI et des installateurs sont alignés, et les notes de version indiquent le nouveau seuil lorsque le changement peut affecter les utilisateurs compilant depuis les sources.
• Aucune donnée personnelle ou sensible n’a été divulguée dans les artefacts de diff ; les tests utilisent des espaces réservés neutres, spécifiques au projet.
• Les conventions de nommage et les frontières d’architecture suivent les contrats du projet (AGENTS.md, Vue d’ensemble de l’architecture).

Révision de la surface de dérive

Considérez toute nouvelle surface interprétative dupliquée comme un risque pour la revue. Une PR ne doit pas ajouter de commentaires, d’exemples, d’instantanés générés, de tables de correspondance, de miroirs de configuration ou de registres parallèles qui reformulent un comportement déjà défini par le code, les schémas, les tests, WIT, la configuration ou le dispatch à l’exécution, sauf si la nouvelle surface est dérivée mécaniquement de cette source ou y renvoie clairement.

Bloquez ou demandez des modifications lorsque la nouvelle surface peut diverger et que les futurs lecteurs, réviseurs ou systèmes d’automatisation pourraient la considérer comme faisant davantage autorité que la source. Parmi les exemples courants figurent les commentaires qui décrivent un comportement que le code n’impose pas, la documentation qui recopie manuellement une liste d’énumération ou de schéma, les tests qui capturent un détail d’implémentation plutôt qu’un comportement observable par l’utilisateur, et les registres qui recopient un espace de clés dont un autre module est déjà responsable.

Privilégiez l’une de ces résolutions :

• Supprimer la surface dupliquée et rendre le propriétaire canonique plus lisible.
• Générer la surface secondaire à partir du propriétaire canonique.
• Remplacez la reformulation par un pointeur vers la source accompagné de la raison pour laquelle ce pointeur doit s’y trouver.

Les commentaires why restent les bienvenus lorsqu’ils capturent des invariants, des risques ou des compromis non évidents que le système de types et les tests ne peuvent pas exprimer. Ils doivent expliquer l’intention, et non reformuler le flux de contrôle voisin ni devenir un second contrat.

Dispatch typé pour les espaces de clés partagés

Pour les espaces de clés partagés, tels que les noms de méthodes wire, les clés de type de canal compilées, les emplacements de providers ou les clés de registre frontend/backend, appliquez cette règle en résolvant les chaînes brutes à la frontière de l’API ou de la configuration. Le code en aval doit effectuer la répartition via une enum, une table générée par macro, un registre de traits/factories ou un autre propriétaire canonique. N’ajoutez pas de branches match de chaînes parallèles, de tables de dispatch écrites à la main ni de listes dupliquées qui doivent être maintenues synchronisées par la mémoire des reviewers.

Ceci n’interdit pas les constantes de chaîne aux frontières d’API. Cela empêche une seconde surface de répartition où l’ajout d’une nouvelle variante peut compiler tout en ignorant silencieusement un consommateur. De bons exemples sont le registre RPC Method pour les noms de méthodes réseau et CHANNEL_COMPILE_SPECS pour les clés de compilation de canal, où un unique propriétaire canonique pilote la couverture en aval.

Liste de vérification de révision approfondie (uniquement pour les risques élevés)

Pour les PR portant risk:high ou domain:security, vérifiez un exemple concret dans chaque catégorie. Un cas concret vaut mieux que cinq affirmations génériques.

• Limites de sécurité : comportement par défaut de refus conservé, aucun élargissement accidentel de la portée.
• Modes de défaillance : gestion des erreurs explicite, dégradation sécurisée.
• Stabilité du contrat : Compatibilité de l’interface de ligne de commande (CLI), de la configuration ou de l’API préservée, ou migration documentée.
• Diff shape : les PR de grande taille ou de nouvelle intégration sont cohérents, la fusion est justifiée maintenant, difficiles à scinder, et ne consistent pas principalement en du code dupliqué.
• Artefacts générés : les fichiers générés qui affectent policy, schema, routes, migrations, lockfiles, release artifacts, capabilities, packages, runtime behavior ou reviewer evidence sont soumis à revue comme du code source.
• Compatibilité de la chaîne d’outils : les modifications du MSRV ou de la chaîne d’outils épinglée sont intentionnelles, alignées entre les environnements CI, Docker et les méthodes d’installation, et documentées pour les utilisateurs de distributions dérivées ou de builds à partir des sources.
• Observabilité : les défaillances doivent être diagnostiquables sans divulguer de secrets.
• Sécurité du rollback : chemin de retour et rayon d’impact clairs.

Forme de la forme

Privilégiez les commentaires sous forme de liste à puces avec un résultat explicite :

• Prêt à fusionner (expliquez pourquoi).
• Nécessite une action de l’auteur (liste des bloqueurs prioritaires).
• Nécessite un examen approfondi de la sécurité ou de l’exécution (indiquez le risque exact et les preuves demandées).

Les commentaires vagues créent des allers-retours inutiles. Si vous vous surprenez à écrire « cela pourrait poser problème », prenez 30 secondes supplémentaires pour le transformer en un scénario précis ou supprimez le commentaire.

Triage des problèmes

Le même principe de routage des risques s’applique aux problèmes, mais les étiquettes et les signaux sont différents.

Les libellés risk:* des issues décrivent le rayon d’impact probable du correctif d’après le rapport. Les libellés risk:* des PR décrivent le diff réel en cours de revue. Réévaluez le risque lorsqu’une issue devient une PR au lieu de reporter automatiquement le libellé de l’issue.

Étiquettes de tri

Assignee signifie un travail actif. La preuve de routage indique pourquoi un problème nécessite une protection spéciale contre l’obsolescence, un traitement par le tracker, ou une décision différée du mainteneur. status:blocked nécessite uniquement le bloqueur non résolu enregistré, sauf s’il nécessite également une protection status:no-stale distincte. Le contrat du tableau de projet définit les sources de preuve acceptées et les résultats de routage. Les labels peuvent identifier le domaine probable, mais les labels seuls ne constituent ni une appropriation ni une protection contre l’obsolescence.

Étiquettes de résolution

Utilisez les étiquettes de résolution uniquement lors de la fermeture ou de la suppression d’un élément de la file d’attente active. Elles expliquent le résultat final ; elles ne remplacent pas les étiquettes de cycle de vie status:* sur les travaux qui doivent rester ouverts. Le guide des étiquettes fait foi pour les définitions actuelles des étiquettes de résolution et les restrictions de migration.

Pour les doublons, indiquez la cible canonique avant de fermer ou de rediriger la discussion. Pour les rapports invalides, expliquez ce qui rend le rapport inexploitable ou vers où il devrait être dirigé. Pour le travail que nous choisissons explicitement de ne pas poursuivre, utilisez le chemin Won't Do au niveau du tableau / wontfix en direct et laissez une brève justification.

Pour les PR ou les chemins d’issue remplacés, utilisez Superseding PRs et conservez l’attribution des contributeurs lorsque cela est pertinent.

Si les journaux ou les charges utiles dans le rapport contiennent des identifiants personnels ou des données sensibles, demandez leur masquage avant d’effectuer un triage plus approfondi. Le processus de triage ne doit pas propager l’exposition.

Gestion des discussions

Les discussions ne constituent une surface communautaire maintenue que lorsqu’un responsable ou une cadence de revue existe. La cadence par défaut est un passage hebdomadaire du mainteneur sur les fils nouveaux et récemment actifs. Un responsable désigné peut prendre en charge ce passage sur la surface, mais le responsable maintient la surface ; il ne devient pas le propriétaire de chaque question, idée ou implémentation qui y apparaît.

À chaque passe de Discussions :

1. Vérifiez les fils de discussion nouveaux et récemment actifs pour l’adéquation à la catégorie, les questions-réponses sans réponse, le spam, les données sensibles et les fils ayant abouti à un résultat concret pour le projet.
2. Conservez les conversations communautaires légères dans Discussions lorsqu’elles sont encore exploratoires, peuvent y trouver une réponse, ou s’avèrent utiles en tant que vitrine, démo, sondage, annonce ou fil de discussion pour recueillir des retours généraux.
3. Promouvez les résultats concrets vers la surface suivie appropriée : les bugs et les périmètres de fonctionnalités acceptés vers les issues, les propositions d’architecture vers les issues RFC, les détails spécifiques aux PR vers les commentaires de PR, les règles opérationnelles durables vers la documentation des mainteneurs ou des contributeurs.
4. Clôturez la boucle dans la Discussion d’origine avec un bref résumé et un lien vers l’issue, la RFC, la PR ou le document qui détient désormais le résultat. Ne marquez une réponse que lorsque la catégorie et le résultat le rendent exact.
5. Redirigez les fils sensibles en matière de sécurité vers le canal privé de signalement des vulnérabilités décrit dans Problèmes de sécurité, traitez les données sensibles conformément à Confidentialité et fermez les fils purement publicitaires ou sans rapport avec le projet. Conservez les démonstrations ou intégrations utiles liées au projet comme contenu de vitrine communautaire lorsqu’elles ne demandent pas aux mainteneurs de suivre un travail.

Si les Discussions ne sont pas examinées selon la cadence documentée, ne les présentez pas comme une voie d’entrée obligatoire. Considérez-les comme une archive passive jusqu’à ce qu’un responsable ou une cadence soit rétabli.

Nettoyage du backlog des PR

Utilisez l’instantané de la file d’attente en mode rapport uniquement lors de la sélection de la prochaine passe de revue :

python3 scripts/github/pr_review_queue.py --queue all --older-than-days 7 --format table

La commande fournit une vue à la demande de l’état actuel de GitHub, et non une file d’attente durable ni une source d’autorité en matière de fusion. Cet instantané all exécute les volets communs indépendamment, de sorte qu’une même PR peut apparaître dans plusieurs volets ; ajoutez --author LOGIN pour inclure mine. Utilisez --queue near-ready pour commencer par les PR aiguillées par les mainteneurs dont la recherche GitHub a abouti ; cela donne la priorité aux candidates qui pourraient être plus proches de la fusion, sans prétendre qu’elles sont fusionnables ou qu’elles disposent de suffisamment d’approbations. Utilisez --format json pour l’inspection ou la génération de rapports en aval, et --format links pour obtenir des liens de recherche GitHub. La recherche GitHub fournit les listes de candidates ; le script ne lit les timelines que pour déterminer l’ancienneté de la dernière action de l’auteur, et les revues uniquement pour l’affectation à un second Core sur le commit de tête actuel. Les détails manquants ou ambigus restent inconnus. Confirmez la possibilité de fusion, les vérifications et la prise en compte des approbations lors de la revue proprement dite. Donnez la priorité aux PR parentes Depends on #... et examinez-les avant leurs enfants ; lorsqu’un parent ne peut pas être examiné, reportez l’examen approfondi de l’enfant, sauf si une partie indépendante et délimitée bénéficie d’un examen anticipé ; actualisez alors l’enfant et revalidez-le après la fusion du parent. Les PR empilées restent un volet de rapport distinct et ne deviennent pas prêtes pour la revue simplement parce qu’elles sont anciennes.

Lorsque la demande de révision dépasse la capacité :

1. Maintenez les PRs de bugs et de sécurité actives en tête de la file d’attente (size:XS ou size:S).
2. Demandez la consolidation des PR qui se chevauchent ; fermez les plus anciennes en justifiant par leur remplacement (superseded ou replaced) après accord de l’auteur. Consultez Remplacement des PR pour les règles d’attribution.
3. Utilisez la montée en charge des PR obsolètes ci-dessous. L’élagage du backlog des PR utilise needs-author-action et stale-candidate ; les balayages des issues obsolètes utilisent status:stale selon la politique canonique des issues obsolètes.

Lorsqu’un mainteneur soumet une revue de type request-changes et que l’étape suivante incombe à l’auteur de la PR, appliquez needs-author-action dans le même paquet de revue/label. Ne l’ajoutez pas lorsque le changement demandé peut être corrigé par un mainteneur et qu’un mainteneur prévoit de pousser le nettoyage, lorsqu’un autre mainteneur ou propriétaire reprend la branche, ou lorsque le blocage attend une décision d’un mainteneur plutôt qu’un travail de l’auteur.

Si le bug ou la fonctionnalité sous-jacente est toujours valide, conservez-le dans un ticket, une ligne de suivi, un PR de remplacement ou un plan de reprise, au lieu de sous-entendre que l’idée a été rejetée. Exigez un rebase et des preuves de validation récentes avant de rouvrir tout élément clos pour inactivité.

Dérogation à l’automatisation

Utilisez ceci lorsque la sortie de l’automatisation crée des effets secondaires de révision :

1. Libellé de risque incorrect : définissez le libellé risk:* prévu. Si l’automatisation des risques est activée à l’avenir, respectez également le contrat d’automatisation des libellés pour risk:manual ; la dérogation ne contourne pas la règle d’approbation risk:high OR domain:security.
2. Fermeture automatique incorrecte lors du triage des issues : rouvrir, supprimer le label de routage, laisser un commentaire de clarification.
3. Spam d’étiquettes ou bruit : conservez un seul commentaire canonique du mainteneur, supprimez les étiquettes de routage redondantes.
4. Périmètre de PR ambigu : demandez une scission avant une revue approfondie ; n’essayez pas de mener une revue couvrant deux préoccupations à la fois.

Transfert

Lorsque vous transmettez une revue à un autre mainteneur ou agent en cours de route, incluez :

1. Résumé de la portée.
2. Classe de risque actuelle et justification.
3. Ce que vous avez validé.
4. Bloquants ouverts.
5. Action suivante suggérée.

Cela permet de minimiser la perte de contexte et d’éviter que le prochain réviseur ne refasse les mêmes requêtes que vous avez déjà effectuées.

Hygiène de la file d’attente hebdomadaire

• Parcourez la file d’attente des éléments obsolètes. Appliquez status:no-stale uniquement selon les règles du contrat du tableau de projet : lorsqu’un travail accepté ou autrement de longue durée a une raison enregistrée de rester ouvert, des preuves de routage visibles par les contributeurs, et qu’aucune autre exclusion d’obsolescence ne s’applique déjà. Les trackers de version actifs et les trackers de RFC ou de conception actifs peuvent conserver la protection contre l’obsolescence par défaut lorsque l’issue elle-même identifie clairement la surface de coordination ou de décision active ; réexaminez-les lorsque le jalon se clôture, que le tracker s’écarte de l’état réel, que la RFC aboutit à une décision, est remplacée ou clôturée, ou que l’issue cesse de représenter une surface de décision de projet active. Tant que l’audit d’exemption d’obsolescence n’est pas effectué, traitez les issues status:no-stale existantes auxquelles il manque ces éléments comme des constats d’audit plutôt que comme des candidates automatiques à l’obsolescence.
• Priorisez d’abord les PRs de bugs et de sécurité size:XS ou size:S.
• Transformer les questions récurrentes de support en améliorations de la documentation et en conseils pour les réponses automatiques.

L’objectif est une file d’attente où chaque PR ouverte est soit en cours de revue active, soit bloquée en attente de l’auteur, soit bloquée par un élément externe, mais ne reste jamais en attente simplement parce que personne ne s’en est occupé.