Pull requests et code review

Une pull request (PR), ou merge request (MR) sur GitLab, est une demande d'intégration de votre branche dans une autre. C'est le mécanisme central de la collaboration moderne : votre code est relu, discuté et validé avant d'être mergé. Ce guide couvre le workflow complet, de la création à l'intégration.

Prérequis : Workflows distribués et Merge et conflits.

Ce que vous allez apprendre

Créer une Pull Request bien structurée pour faciliter la revue
Conduire une revue de code constructive sans bloquer l'équipe
Naviguer dans le cycle de vie d'une PR de l'ouverture à la fusion
Gérer les retours : amendments, force-push et itérations

Le cycle de vie d'une PR

Les huit étapes ci-dessous se déroulent à deux endroits distincts, et c'est la principale source de confusion pour qui débute. Les étapes 1, 2 et 5 se passent dans votre dépôt local, avec des commandes git. Les étapes 3 à 8 se passent sur la forge, GitHub ou GitLab, dans une interface web. La pull request elle-même n'existe pas dans Git : c'est un objet propre à la forge, qui suit l'évolution d'une branche déjà poussée.

Notez aussi que la boucle 4 à 5 se répète autant de fois que nécessaire. Une PR qui repart en correction n'est pas un échec, c'est le fonctionnement normal du processus.

1. Créer une branche
        ↓
2. Commiter et pousser
        ↓
3. Ouvrir la PR
        ↓
4. Review + discussions
        ↓
5. Corrections (si demandées)
        ↓
6. Approbation
        ↓
7. Merge
        ↓
8. Suppression de la branche

Créer une PR : le workflow Git

Cinq commandes suffisent avant d'ouvrir la PR. L'étape la plus souvent oubliée est la troisième : le git rebase origin/main rejoue vos commits sur la version la plus récente de main. Vous découvrez les conflits sur votre poste, où vous avez vos outils, au lieu de les laisser apparaître dans l'interface web de la forge où la résolution est nettement plus pénible.

Le -u du git push de l'étape 4 associe une bonne fois pour toutes votre branche locale à celle du dépôt distant. Les git push suivants se feront sans argument, tant que vous vous contentez d'ajouter des commits. Si vous rejouez un rebase après avoir déjà poussé, l'historique diverge et le push est refusé : utilisez alors git push --force-with-lease, qui refuse d'écraser le travail d'un collègue arrivé entre-temps, contrairement à --force.

Créez une branche depuis main à jour :

git switch main
git pull origin main
git switch -c feature/user-avatar

Travaillez avec des commits atomiques :

# Chaque commit = un changement logique
git add src/components/Avatar.tsx
git commit -m "feat: ajouter le composant Avatar"

git add src/pages/profile.tsx
git commit -m "feat: intégrer Avatar dans la page profil"

Rebasez sur main avant de pousser (pour éviter les conflits) :
Fenêtre de terminal
```
git fetch origin
git rebase origin/main
```
Poussez votre branche :
Fenêtre de terminal
```
git push -u origin feature/user-avatar
```
Ouvrez la PR sur GitHub/GitLab via l'interface web

Rédiger une bonne PR

Une PR bien rédigée accélère la review et réduit les allers-retours.

Le titre

Le titre est ce que verront vos collègues dans une liste de vingt PR ouvertes, et c'est aussi lui qui deviendra le message de commit sur main si l'équipe pratique le squash. Il doit annoncer le résultat obtenu, pas l'activité menée : « ajouter le composant Avatar » se comprend, « travail sur le profil » n'apprend rien. Le préfixe conventionnel (feat:, fix:, docs:) permet en prime aux outils de génération de changelog de classer la modification.

Court, descriptif, au format conventionnel :

feat: ajouter le composant Avatar avec upload d'image
fix: corriger le redirect après déconnexion
docs: documenter l'API de notifications

La description

La section qui fait le plus gagner de temps est Comment tester. Sans elle, le relecteur doit deviner la manipulation à effectuer et se contente souvent de lire le diff, ce qui laisse passer les régressions fonctionnelles. La section Contexte répond de son côté à la question qu'un relecteur ne posera pas toujours à voix haute : pourquoi ce changement maintenant, et quelle alternative a été écartée.

Structurez avec ces sections :

## Contexte
Pourquoi cette modification est nécessaire.

## Changements
- Ajout du composant `Avatar` (upload + crop)
- Intégration dans la page profil
- Tests unitaires pour le crop

## Comment tester
1. Aller sur /profil
2. Cliquer sur l'avatar
3. Uploader une image > 2 Mo → vérifier le message d'erreur

## Captures d'écran
(si changement visuel)

Bonnes pratiques de taille

La taille d'une PR est le facteur qui pèse le plus sur la qualité de la revue. Au-delà de quelques centaines de lignes, l'attention du relecteur baisse et les commentaires se déplacent vers ce qui est facile à repérer, le nommage et le formatage, au détriment de la logique métier. La colonne Qualité du tableau traduit ce phénomène : elle qualifie la revue, pas le code soumis.

Taille de PR	Lignes modifiées	Temps de review	Qualité
Petite	< 200	15-30 min	Excellente
Moyenne	200-500	30-60 min	Bonne
Grande	> 500	> 1h	Médiocre

Visez des PR de moins de 200 lignes. Au-delà, découpez en plusieurs PR dépendantes.

La draft PR

Si votre travail n'est pas terminé mais que vous voulez un retour précoce, ouvrez une draft PR :

GitHub : bouton « Create draft pull request »
GitLab : préfixez le titre avec Draft: ou cochez l'option

La draft PR signale aux reviewers que le code n'est pas prêt pour le merge mais que des retours sont bienvenus sur l'approche.

Faire une revue de code

Ce qu'il faut chercher

Parcourez ces six catégories dans l'ordre du tableau, du plus coûteux au moins coûteux à corriger après coup. Une faille de sécurité ou une erreur de logique repérée en revue vaut des heures de débogage évitées ; un problème de convention de style se règle en trente secondes et devrait de toute façon être détecté par un linter automatique, pas par un humain. Si votre revue ne contient que des remarques de la dernière ligne, c'est le signe qu'il manque un outillage dans la chaîne d'intégration.

Catégorie	Points à vérifier
Logique	Le code fait-il ce qu'il prétend ? Cas limites ?
Lisibilité	Noms clairs ? Structure compréhensible ?
Tests	Couvrent-ils les cas importants ?
Sécurité	Injection, XSS, secrets en dur ?
Performance	Requête N+1, boucle coûteuse ?
Conventions	Style du projet respecté ?

Rédiger des commentaires constructifs

Les commentaires de review doivent être précis, bienveillants et actionnables :

Au lieu de...	Écrivez...
« C'est nul »	« Cette approche risque X. Et si on faisait Y ? »
« Pourquoi t'as fait ça ? »	« Quelle est la raison de ce choix ? Je me demande si Z serait plus maintenable. »
« Change ça »	« Suggestion : renommer `data` en `userProfile` pour plus de clarté. »

Les niveaux de commentaire

Sans convention, l'auteur d'une PR ne sait pas distinguer une remarque facultative d'une demande bloquante, et il traite tout au même niveau : soit il corrige des détails inutiles, soit il ignore un point important. Ces préfixes sont une convention d'équipe informelle, largement répandue mais non standardisée : notez-la dans le fichier de contribution du dépôt pour que les nouveaux arrivants la connaissent.

Préfixez vos commentaires pour indiquer leur importance :

nit:, détail cosmétique, non bloquant
suggestion:, idée d'amélioration, discutable
question:, demande de clarification
concern:, point potentiellement problématique
(pas de préfixe), changement requis avant merge

Stratégies de merge

Au moment du merge, trois options s'offrent à vous. Elles ne changent rien au contenu final des fichiers sur main : le code obtenu est identique dans les trois cas. Ce qui diffère, c'est la forme de l'historique, donc la facilité avec laquelle vous retrouverez plus tard l'origine d'une régression avec git log, git blame ou git bisect.

Stratégie	Résultat	Avantage	Inconvénient
Merge commit	Commit de merge + historique complet	Traçabilité exacte de la PR	Graphe en losange, `git log` plus difficile à lire
Squash and merge	Un seul commit sur `main`	Historique de `main` très propre	Perd le détail des commits de la PR
Rebase and merge	Commits rejoués linéairement sur `main`	Historique linéaire avec commits individuels	Les hashes changent, attribution des auteurs peut varier

Le piège fréquent est de mélanger les stratégies : certaines PR sont squashées, d'autres mergées avec un commit de fusion, d'autres encore rebasées. L'historique de main devient alors illisible.

Recommandation : choisissez une seule stratégie et configurez-la comme défaut dans les paramètres du dépôt (GitHub : Settings → General → « Allow ... merge », GitLab : Settings → Merge Requests).

Squash : recommandé pour les équipes qui veulent un git log lisible sur main (une ligne par fonctionnalité) et dont les commits intermédiaires sont des WIP
Merge commit : recommandé quand la traçabilité fine des commits est importante (audit, régression via git bisect)
Rebase : recommandé quand vous voulez des commits atomiques sur main sans commits de merge, mais que chaque commit de la PR est déjà propre et significatif

Protéger la branche principale

Tout ce qui précède repose sur une convention d'équipe, et une convention se contourne, souvent sans mauvaise intention, un vendredi soir. Les règles de protection transforment cette convention en contrainte appliquée par la forge : plus personne ne peut pousser directement sur main, y compris les administrateurs si vous cochez l'option correspondante.

Configurez des règles de protection sur main :

Revue obligatoire : au moins 1 (ou 2) approbation(s) avant merge
CI/CD passante : les tests doivent être verts
Branche à jour : la branche doit être rebasée sur main
Pas de push direct : tout passe par une PR

Sur GitHub : Settings → Branches → Branch protection rules. Sur GitLab : Settings → Repository → Protected branches.

Dépannage : problèmes courants

Trois de ces quatre situations se règlent dans votre dépôt local, pas dans l'interface de la forge : la PR reflète l'état de la branche distante et se met à jour d'elle-même dès que vous poussez. Attention à la première ligne, la seule qui impose un force-push : après un rebase, préférez toujours git push --force-with-lease à git push --force, faute de quoi vous risquez d'écraser les commits qu'un collègue aurait poussés sur la même branche.

Symptôme	Cause probable	Solution
PR avec conflits	Branche pas à jour avec `main`	`git rebase origin/main` puis force-push
« CI failed » sur la PR	Tests cassés ou linting	Corrigez localement, poussez un nouveau commit
Reviewer ne répond pas	PR trop grosse ou mal décrite	Découpez, améliorez la description, relancez poliment
Historique pollué de « fix review »	Commits de correction post-review	`git rebase -i` pour squasher avant merge

À retenir

Une PR = un sujet, de préférence < 200 lignes
Titre conventionnel (feat:, fix:, docs:) + description structurée
La draft PR permet d'obtenir un retour précoce
Les commentaires de review sont précis et bienveillants
Protégez main : revue obligatoire + CI passante
Choisissez une stratégie de merge cohérente dans l'équipe

Prochaines étapes

Workflows Git Gitflow, Feature Branch, Trunk-Based : comparez les stratégies.

Maintenir un projet Accepter les contributions et préparer des releases.

Réécrire l'historique Nettoyez vos commits avant d'ouvrir une PR.