Résumé

  • CODEOWNERS est une règle de correspondance par chemin et par branche : GitHub peut demander automatiquement une revue aux propriétaires concernés pour une pull request non brouillon.
  • Le résultat dépend de la branche de base, de l’emplacement du fichier, de l’ordre des motifs, des chemins modifiés et des droits effectifs des propriétaires. Voir un fichier aujourd’hui ne prouve pas le résultat d’hier.
  • Un reçu de revue utile doit conserver séparément la configuration applicable, le diff, la demande, la réponse de revue et les autres conditions de fusion.

Le fichier ne raconte pas l’événement

Dire « les propriétaires ont revu le changement » peut couvrir des réalités très différentes. De quelle branche vient le fichier ? Quels chemins étaient dans la pull request ? Quel motif a gagné ? Les personnes nommées avaient-elles alors les droits requis ? Ont-elles reçu une demande, puis répondu ? Et une approbation de propriétaire était-elle réellement exigée ? Un fichier lisible dans le dépôt n’est qu’une partie de cette histoire.

La documentation de GitHub présente CODEOWNERS comme une configuration qui définit les personnes ou équipes responsables du code. Quand une pull request non brouillon modifie du code possédé, GitHub demande automatiquement une revue aux propriétaires. Pour une pull request marquée brouillon, cette demande n’est pas automatique avant son passage à l’état prêt pour revue. La distinction est simple mais importante : orienter une notification ne constitue pas la trace d’un examen accompli.

La branche de base est déterminante. Chaque fichier CODEOWNERS concerne une branche, et GitHub utilise la version présente sur la branche que la pull request doit modifier. Une même modification visant main ou une branche de maintenance peut donc produire des propriétaires différents. Pour une pull request venant d’un fork vers l’amont, c’est le fichier de la branche de base amont qui est utilisé. Le fichier apporté par la branche source, ou le fichier visible plus tard dans la branche par défaut, n’est pas la preuve de la règle qui s’appliquait.

L’emplacement compte lui aussi. GitHub cherche d’abord .github/, puis la racine, puis docs/, et utilise le premier fichier trouvé. Un fichier supérieur à trois mégaoctets n’est pas chargé ; les propriétaires ne sont alors ni affichés ni sollicités. Une règle écrite dans un dépôt peut donc ne pas être une règle active pour l’événement dont on parle.

Un ordre de lignes, une autorité différente

Les motifs donnent facilement une impression d’accumulation. GitHub précise pourtant que le dernier motif correspondant l’emporte. Une règle générale * peut être remplacée, pour un changement JavaScript, par une règle *.js placée ensuite. Deux propriétaires sur la même ligne partagent le motif ; les mettre sur deux lignes correspondantes peut au contraire faire disparaître le premier résultat. Citer la règle générale sans reconstruire l’ordre revient à attribuer une responsabilité qui n’était peut-être pas celle de la pull request.

Les autres conditions sont tout aussi concrètes. Les chemins sont sensibles à la casse. Une ligne invalide est ignorée. Un utilisateur ou une équipe inexistant, ou sans accès suffisant, n’est pas attribué comme propriétaire. Ces faits ne désignent aucun dépôt fautif ; ils rappellent qu’un texte de politique n’est pas une preuve automatique de son exécution.

GitHub recommande aussi de définir un propriétaire pour le fichier CODEOWNERS lui-même. La recommandation révèle le point de gouvernance : une règle qui distribue la responsabilité doit rendre visible sa propre voie de modification. Sans cela, un lecteur peut connaître les propriétaires déclarés du code sans savoir qui pouvait modifier la déclaration.

La revue n’épuise pas le contrôle

GitHub distingue la demande automatique de revue de l’exigence, optionnelle, d’une approbation de propriétaire avant fusion. Cette dernière est configurée séparément par un administrateur ou un propriétaire du dépôt. Lorsque la règle s’applique, l’approbation d’un seul des propriétaires d’un même motif peut suffire. Le fichier seul n’impose donc pas à lui seul une porte de fusion.

Les contrôles applicables peuvent aussi se superposer. Les rulesets et les règles de protection de branche fonctionnent ensemble ; les règles applicables s’agrègent, et la version la plus restrictive d’une règle commune prévaut. Des approbations, contrôles de statut, déploiements réussis, commentaires résolus, méthode de fusion et permissions de contournement peuvent relever de surfaces séparées. GitHub note même qu’une pull request ayant toutes ses revues requises peut rester bloquée si une autre pull request sur le même commit de tête possède une revue en attente ou rejetée.

Une approbation garde toute sa valeur : elle signale que les changements semblent prêts à être fusionnés. Mais elle doit conserver son objet. Elle décrit une revue, pour un diff, par un acteur, dans un contexte. Elle ne transforme pas à elle seule un fichier de routage en historique complet de la décision.

Conserver un reçu configuration-vers-revue

Pour une affirmation importante, un reçu compact devrait commencer par l’identifiant de pull request, les références de base et de tête, et les chemins modifiés. Il doit ensuite conserver l’emplacement et l’identité du contenu CODEOWNERS de la branche de base, le motif qui a correspondu et les propriétaires résolus. Viennent ensuite la demande de revue et la réponse, avec leur date et le diff couvert.

Si le récit va jusqu’à la fusion, il doit nommer séparément les règles de protection ou rulesets applicables, les états observés de leurs conditions et tout contournement documenté. Là où une jonction n’est pas attestée, la phrase doit s’arrêter. Ce n’est pas une nouvelle procédure GitHub : c’est une manière de ne pas présenter une configuration actuelle comme la preuve complète d’un événement passé.

Sources

  1. GitHub Docs — About code owners
  2. GitHub Docs — Pull request reviews
  3. GitHub Docs — About rulesets
  4. GitHub Docs — Available rules for rulesets