Rédiger une description de pull request claire pas-à-pas

Une pull request mal décrite ralentit toute l’équipe. Le relecteur doit deviner ce que le code change, pourquoi, et quels effets de bord vérifier. Le résultat : la revue traîne, des allers-retours s’accumulent, parfois la PR finit acceptée par lassitude sans véritable contrôle. Une description claire, à l’inverse, fait économiser à chaque relecteur dix à trente minutes de fouille mentale et augmente nettement la qualité de la revue. Ce tutoriel décrit un protocole reproductible en huit étapes pour rédiger des descriptions de pull requests qui se font valider rapidement et sans malentendu.

Article principal : Soft-skills indispensables aux métiers de l’IT en 2026. Cet article fait partie d’une série sur les compétences comportementales en ingénierie.

Prérequis

• Compte GitHub, GitLab ou Bitbucket actif, avec au moins une PR déjà ouverte par le passé
• Git installé localement (vérification via git --version en ligne de commande)
• Un éditeur capable de prévisualiser du Markdown (VS Code, IntelliJ, Vim avec plugin vim-markdown, ou simplement l’aperçu intégré de GitHub)
• Niveau attendu : développeur junior ou intermédiaire
• Temps estimé pour terminer le tutoriel : 45 à 60 minutes, plus 15 minutes par PR ensuite

Étape 1 — Comprendre ce que cherche le relecteur

Avant d’écrire un seul mot de description, il faut se mettre à la place du relecteur. Quand un collègue ouvre votre PR, il a typiquement entre cinq et trente minutes à lui consacrer, partagés avec son propre travail en cours. Sa première question silencieuse n’est pas « quelles sont les lignes modifiées ? » mais « est-ce que je dois lire ça maintenant, et qu’est-ce que je vais y trouver ? ». La description doit répondre à ces deux questions en quinze secondes de lecture.

Concrètement, le relecteur cherche à reconstituer trois choses : le problème que la PR résout (le quoi), la raison pour laquelle on a choisi cette solution plutôt qu’une autre (le pourquoi), et les zones du code à inspecter avec attention (le où). Si votre description couvre ces trois axes, vous êtes déjà au-dessus de la moyenne du secteur.

Cet exercice mental prend trente secondes. Faites-le systématiquement avant d’écrire — c’est ce qui transforme une description bavarde et inutile en un message dense et actionnable.

Étape 2 — Mettre en place un template de description

La majorité des plateformes de gestion de code (GitHub, GitLab) supportent les pull request templates. Un template est un fichier Markdown placé dans le dépôt qui pré-remplit la description chaque fois qu’on ouvre une PR. C’est l’investissement à plus fort retour qu’on puisse faire en cinq minutes.

Le template force chaque membre de l’équipe à structurer son écrit, et il rappelle de ne pas oublier les sections critiques (tests, captures, breaking changes). Voici un template minimaliste à placer à la racine du dépôt sous le chemin .github/pull_request_template.md pour GitHub :

## Pourquoi ce changement
<!-- Le problème résolu, en 2-3 phrases. Lien vers le ticket si applicable. -->

## Ce qui change
<!-- La solution adoptée, du point de vue fonctionnel puis technique. -->

## Comment vérifier
<!-- Étapes pour tester localement ou en staging. Captures si UI. -->

## Risques et points d'attention
<!-- Effets de bord possibles, zones du code sensibles, breaking changes. -->

## Checklist
- [ ] Tests ajoutés ou mis à jour
- [ ] Documentation mise à jour si nécessaire
- [ ] Pas de secret commité (variables d'environnement, clés API)

Une fois ce fichier commité sur la branche par défaut, GitHub charge automatiquement son contenu dans le champ description de chaque nouvelle PR. L’équipe gagne un cadre commun, le relecteur sait où chercher l’information, et l’auteur ne part plus de la page blanche. Pour GitLab, le chemin équivalent est .gitlab/merge_request_templates/Default.md.

Étape 3 — Rédiger un titre qui passe le test des trente caractères

Le titre de la PR est lu par tous, parfois sans même ouvrir la description. Il apparaît dans les notifications, dans la liste des PR ouvertes, dans les release notes générées automatiquement, et dans l’historique git après merge. Il doit donc tenir tout seul.

La règle pratique : le titre doit être compréhensible sans contexte par quelqu’un qui n’a pas vu le ticket associé, en moins de soixante caractères. Si vous coupez à trente caractères, le sens essentiel doit encore tenir.

Comparons trois titres pour la même PR :

❌ Fix bug
❌ WIP - changes for the feature
✅ feat(auth): refresh token expirant après 24h au lieu de 7j

Le premier ne dit rien. Le deuxième dit que c’est en cours, ce qui n’apporte rien (le statut « brouillon » de GitHub le dit déjà). Le troisième suit la convention Conventional Commits 1.0.0 avec un type (feat), un scope (auth), et une description précise. Cette dernière forme rend possible la génération automatique de changelogs, les releases sémantiques, et le filtrage rapide dans l’historique.

La spécification Conventional Commits définit notamment que les commits de type fix correspondent à un incrément PATCH (1.2.3 → 1.2.4), feat à un incrément MINOR (1.2.3 → 1.3.0), et un footer BREAKING CHANGE: à un incrément MAJOR (1.2.3 → 2.0.0). Adopter cette convention dès le titre de la PR aligne automatiquement l’équipe sur le versionnage sémantique sans effort supplémentaire.

Étape 4 — Rédiger la section « Pourquoi »

C’est la section la plus négligée et la plus importante. Le code lui-même répond déjà au « quoi » et au « comment » — pas besoin de paraphraser le diff. Le « pourquoi », en revanche, n’est nulle part dans le code, sauf si l’auteur le rend explicite. Six mois plus tard, quand un collègue lira ce commit dans git blame, c’est cette section qu’il cherchera.

La structure efficace tient en trois phrases : la situation initiale, le problème observé, le résultat attendu après le changement. Voici un exemple concret :

## Pourquoi ce changement

Les tokens d'accès actuels expirent au bout de 7 jours, ce qui force
les utilisateurs à se reconnecter chaque semaine. Le ticket #2841
remonte 12 plaintes sur ce point en deux mois. On réduit la durée
à 24h sur le token court, et on ajoute un refresh token de 30 jours
pour préserver la session sans exposer le token court trop longtemps.

Cette description fait trois choses en cinq lignes : elle pose le contexte (durée actuelle), elle prouve l’impact utilisateur (12 plaintes), et elle annonce la solution (split token + refresh). Le relecteur sait immédiatement si la décision est légitime et peut concentrer sa revue sur la mise en œuvre. Si vous n’arrivez pas à écrire cette section parce que vous ne savez pas pourquoi vous faites ce changement, c’est un signal — il faut probablement reparler avec le product owner avant de coder.

Étape 5 — Rédiger la section « Ce qui change »

Cette section décrit la solution sans paraphraser le diff. Elle explique les choix d’architecture qui ne sautent pas aux yeux à la lecture du code. Elle anticipe les questions que le relecteur va poser, et y répond avant qu’il les pose. C’est aussi l’endroit où signaler un refactoring incident (« j’ai déplacé la fonction X dans le module Y, parce que… »).

Une bonne pratique consiste à séparer les changements fonctionnels des changements techniques. Voici un exemple sur la même PR de tokens :

## Ce qui change

**Côté utilisateur** : la session reste active 30 jours sans
reconnexion, mais expire silencieusement après 30 jours d'inactivité.

**Côté technique** :
- Nouveau modèle `RefreshToken` avec rotation à chaque utilisation
- Endpoint `POST /auth/refresh` ajouté
- Middleware `authenticate` modifié pour accepter les deux tokens
- Migration `20260501_refresh_tokens` ajoute la table

Le scheduler de purge des tokens expirés est dans une PR séparée
(#2855) parce qu'elle dépend d'une migration encore non déployée.

Cette structure permet au relecteur de comprendre le périmètre d’un coup d’œil. La séparation explicite entre la PR courante et la PR liée (#2855) évite la confusion classique où un relecteur cherche du code qui n’est pas censé être là.

Étape 6 — Rédiger la section « Comment vérifier »

Le relecteur ne va pas forcément exécuter le code, mais il doit pouvoir le faire si quelque chose lui semble suspect. Une PR qui ne dit pas comment tester est une PR qui force le relecteur à improviser. Sur une équipe de cinq personnes, ces improvisations s’additionnent en heures perdues chaque semaine.

Cette section doit contenir des commandes copiables, pas des descriptions vagues. Mauvais exemple : « lancer le serveur et tester le login ». Bon exemple :

## Comment vérifier

1. `git checkout feat/refresh-token-rotation && pnpm install`
2. `pnpm migrate` (applique la migration locale)
3. `pnpm dev` puis ouvrir http://localhost:3000/login
4. Se connecter avec `demo@example.com / demo`
5. Dans les DevTools, onglet Application > Cookies, vérifier que :
   - `access_token` expire dans 24h
   - `refresh_token` expire dans 30j
6. Attendre 1 minute, recharger : la requête doit déclencher
   un appel automatique à `/auth/refresh` (visible dans Network).

Avec ces six étapes copiables, le relecteur peut valider en quatre minutes que le comportement attendu est bien là. Ce niveau de précision a un effet secondaire : il force l’auteur à tester réellement son code en local avant d’ouvrir la PR. Beaucoup de bugs sont attrapés à cette étape, sans qu’aucun relecteur n’ait à intervenir.

Étape 7 — Garder la PR petite

La taille d’une PR est l’un des facteurs les plus prédictifs de la qualité de la revue. Les recommandations publiques de Google sur les changelists indiquent qu’environ 100 lignes modifiées est une taille raisonnable, et que 1000 lignes est généralement trop large, même si la décision finale revient au relecteur. Une grosse PR concentre plusieurs problèmes : revue superficielle, allers-retours longs, conflits de merge à répétition, et difficulté à isoler la cause d’un bug si on doit faire un rollback.

La discipline est de découper le travail en unités autonomes avant de coder, pas après. Si une feature demande de toucher à trois couches (DB, API, frontend), idéalement trois PR distinctes, mergées dans cet ordre. Si chaque morceau dépend du suivant, on peut utiliser une chaîne de PR (stacked diffs) où chaque PR a comme base la précédente.

Avant d’ouvrir la PR, exécuter :

git diff --stat origin/main

La sortie liste les fichiers modifiés et le nombre de lignes ajoutées/supprimées par fichier, avec un total en bas. Si le total dépasse 400 lignes (hors fichiers générés type lockfiles), il faut sérieusement envisager de découper. Cette vérification prend trois secondes et évite des journées de revue bloquée. Si le découpage devient impossible parce que les changements sont entrelacés, c’est en général le signe d’un sous-problème de conception qui mérite un refactor préalable.

Étape 8 — Auto-revue avant publication

La dernière étape avant de cliquer sur « Create pull request » est une auto-revue. Concrètement, il s’agit de relire son propre diff comme si on était relecteur externe. Cette pratique attrape une fraction étonnante des défauts qu’un relecteur aurait remontés.

L’astuce qui aide le plus : fermer la PR pendant cinq minutes (boire un verre d’eau, marcher), puis revenir en mode relecteur. Le cerveau passe en mode critique au lieu du mode justification. Pour rendre cette pratique systématique, on peut s’imposer une mini-checklist :

git diff origin/main --stat       # taille raisonnable ?
git diff origin/main | grep -i "todo\|fixme\|console.log\|debugger"
git log origin/main..HEAD --oneline  # commits propres ?

La première commande affiche le résumé pour vérifier la taille. La deuxième détecte les marqueurs de débogage oubliés (logs de console, appels au debugger, TODO non documentés). La troisième liste les commits de la branche pour vérifier qu’ils racontent une histoire lisible — pas dix commits « wip » ou « fix typo ». Si l’historique est sale, un git rebase -i origin/main permet de regrouper et renommer avant de pousser.

Sur la PR elle-même, GitHub permet de laisser des commentaires de l’auteur sur ses propres lignes. C’est très utile pour anticiper une question : « ici je passe par un cast explicite parce que TypeScript n’arrive pas à inférer le type, voir issue X du repo upstream ». Cette pratique économise un aller-retour entier.

Étape 9 — Vérification finale et publication

Une fois la PR ouverte, vérifier en moins de deux minutes que tout est cohérent côté plateforme. Cette dernière passe attrape les détails qui font perdre du temps aux relecteurs.

# Sur la page de la PR :
# - Le titre suit la convention (feat/fix/refactor/docs/...)
# - Les reviewers sont assignés (au moins 1, idéalement 2)
# - Les labels sont posés (priority, area)
# - La CI tourne ou est passée verte
# - Aucun fichier accidentel (.DS_Store, .idea/, fichiers binaires)

Quand ces six points sont OK, la PR est prête pour la revue. La probabilité qu’elle soit mergée en moins de vingt-quatre heures est nettement supérieure à celle d’une PR non préparée. Un signal de réussite : le premier commentaire du relecteur est un commentaire technique précis, pas une question de cadrage du genre « pourquoi tu fais ça ? ».

Erreurs fréquentes

Tutoriels associés

• Conduire une revue de code constructive pas-à-pas — le pendant côté relecteur du présent tutoriel.
• Animer un stand-up et une rétrospective d’équipe pas-à-pas — pour communiquer l’avancement des PR en équipe.

Pour aller plus loin

• 🔝 Retour à l’article principal : Soft-skills indispensables aux métiers de l’IT en 2026
• Spécification Conventional Commits 1.0.0
• Google Engineering Practices — Small CLs
• Dépôt GitHub officiel de la spécification Conventional Commits
• Documentation GitHub — Pull request templates

Questions fréquentes

Faut-il toujours suivre Conventional Commits ?

Pas obligatoirement, mais c’est l’une des conventions les plus largement adoptées et elle débloque l’automatisation (changelogs, semantic-release). Si l’équipe a déjà sa propre convention cohérente, garder la cohérence prime. Si l’équipe n’a aucune convention, Conventional Commits est un bon point de départ par défaut.

Combien de relecteurs assigner ?

Au moins un, idéalement deux. Au-delà de trois, la responsabilité se dilue et personne ne se sent obligé de relire en profondeur. Les code owners définis dans .github/CODEOWNERS permettent d’assigner automatiquement les bonnes personnes selon les fichiers touchés.

Comment gérer une PR qui dépend d’une autre PR non encore mergée ?

Deux options : créer la PR sur la branche de la PR parente plutôt que sur main (mode stacked), ou attendre le merge de la PR parente avant d’ouvrir. La première option permet de travailler en parallèle ; la seconde simplifie la revue. Le choix dépend de l’urgence.

Que faire quand la CI casse à cause d’un test inattendu ?

Reproduire le test en local d’abord, ne jamais le « skip » par confort. Si le test échoue à cause d’un effet de bord (test flaky), ouvrir un ticket dédié et le traiter dans une autre PR. Skipper un test pour passer la CI est un vol de dette technique à toute l’équipe.

Comment formuler une remarque sur sa propre PR sans paraître hésitant ?

Utiliser la formulation factuelle : « j’ai retenu cette approche parce que X, l’alternative aurait été Y mais elle implique Z ». Cette structure montre la réflexion sans l’auto-flagellation et donne au relecteur les éléments pour valider ou contester.

La description doit-elle être en français ou en anglais ?

La règle est de suivre la langue du dépôt. Si les commits passés sont en anglais, écrire en anglais. Si l’équipe est francophone et que le code est privé, le français est parfaitement acceptable. Pour un projet open source, l’anglais est de fait standard.