Comprendre le cycle de vie d'une pull request

Ce que tu vas comprendre

  • Identifier les états possibles d'une PR et les transitions entre eux (Bloom 2)
  • Analyser pourquoi certaines transitions sont automatiques et d'autres manuelles (Bloom 4)
  • Évaluer à quel moment une PR est prête à être fusionnée (Bloom 5)

Le problème concret

Tu as ouvert une PR il y a trois jours. Un reviewer a laissé des commentaires. Tu as poussé des corrections. La CI a repassé au vert. Mais tu ne sais pas si tu dois re-demander une review, si tu peux fusionner maintenant, ou si quelque chose bloque encore. L'état de la PR n'est pas clair.

Comprendre le cycle de vie d'une PR te permet de lire son état actuel d'un coup d'œil et de savoir exactement quelle action effectuer ensuite.

L'analogie

Une pull request ressemble à un dossier de demande de permis de construire :

  • Ouvert : le dossier est déposé, les voisins (reviewers) peuvent faire des remarques
  • En cours de review : l'architecte (reviewer) examine les plans et demande des modifications
  • Approuvé : l'architecte signe les plans modifiés
  • CI verte : les normes techniques sont vérifiées automatiquement (sécurité incendie, etc.)
  • Fusionné : le permis est accordé, les travaux peuvent commencer sur main
  • Refusé / fermé : le dossier est archivé sans suite

Comme pour un permis, une PR peut être rouverte si elle a été fermée par erreur ou prématurément.

Le modèle — diagramme de séquence complet

stateDiagram-v2
    [*] --> Draft : créer en brouillon
    [*] --> Open : créer directement

    Draft --> Open : marquer "Prête pour review"
    Open --> Draft : repasser en brouillon

    Open --> ReviewRequested : assigner un reviewer
    ReviewRequested --> ChangesRequested : reviewer demande modifications
    ReviewRequested --> Approved : reviewer approuve

    ChangesRequested --> ReviewRequested : auteur pousse corrections
+ re-demande review
    Approved --> Open : nouveau push (invalidation auto)

    Open --> Closed : fermer sans fusionner
    Closed --> Open : rouvrir

    Approved --> Merged : fusionner (CI verte requise si configurée)
    Open --> Merged : fusionner (si permissions suffisantes)

    Merged --> [*]
    Closed --> [*]

Les états en détail

Draft (Brouillon)

La PR est visible par l'équipe mais ne peut pas être fusionnée. Utilise cet état pour : - Partager du code en cours de travail pour des commentaires précoces - Réserver un numéro de PR pour une issue - Travailler en collaboration sur la même branche

Transition manuelle : l'auteur clique Marquer comme prête pour review.

Open (Ouverte)

État par défaut à la création. La PR peut être commentée, reviewée et fusionnée (selon les permissions). C'est l'état de travail normal.

ReviewRequested (Review demandée)

Un reviewer a été assigné. gitrust lui envoie une notification. La PR attend son verdict. L'auteur peut continuer à pousser des commits pendant ce temps.

ChangesRequested (Modifications demandées)

Le reviewer a explicitement demandé des changements. La PR est bloquée — elle ne peut pas être fusionnée tant que le reviewer n'a pas approuvé ou n'a pas retiré son refus.

Transition de sortie : l'auteur pousse les corrections et re-demande une review (bouton Re-request review).

Approved (Approuvée)

Au moins un reviewer a approuvé. La PR peut être fusionnée si la CI est verte.

Invalidation automatique : si l'auteur pousse un nouveau commit après l'approbation, le statut repasse à Open — le reviewer doit approuver à nouveau. Ce comportement garantit que ce qui est fusionné correspond exactement à ce qui a été approuvé.

Merged (Fusionnée)

État terminal. Le code est dans la branche cible. La PR est archivée en lecture seule. Si la description contenait closes #N, l'issue N est fermée automatiquement à ce moment.

Closed (Fermée)

Fermée sans fusion — le travail a été abandonné ou la PR était incorrecte. Peut être rouverte si nécessaire. Les commits de la branche ne sont pas supprimés.

Transitions automatiques

Déclencheur Transition
Nouveau commit poussé après approbation Approved → Open (invalidation de l'approbation)
Fusion dans la branche cible Open/Approved → Merged
Fusion + closes #N dans le commit ou la description Issue N → Closed
CI configurée et pipeline échoué Bouton Fusionner désactivé (blocage soft)

Alternatives et compromis

Review obligatoire vs optionnelle

gitrust permet de fusionner une PR sans review externe si l'on a les permissions Owner ou Maintainer. Certaines équipes configurent une branche protégée exigeant au moins une approbation — ce qui rend la review techniquement obligatoire. D'autres s'appuient sur la convention sans protection forcée. La protection forcée convient aux projets critiques ou réglementés ; la convention suffit pour les petites équipes de confiance.

Invalidation automatique après push

Certaines forges (GitHub) ont rendu ce comportement optionnel. gitrust invalide systématiquement l'approbation après un nouveau push — c'est plus strict mais garantit que le reviewer a vu exactement le code fusionné. Inconvénient : un correctif de typo force une re-review complète.

Vérifier ta compréhension

  1. Une PR est à l'état ChangesRequested. L'auteur pousse ses corrections mais ne re-demande pas de review. Que se passe-t-il ? Peut-on fusionner ? (Bloom 2 — identifier l'état)

  2. Tu es Maintainer d'un dépôt. Une PR approuvée contient un conflit de merge introduit par un commit récent sur main. Quelles options as-tu, et quels sont les avantages et inconvénients de chacune ? (Bloom 4 — analyser les compromis)

Pour aller plus loin