Comment Écrire une Pull Request que les Gens Aiment Vraiment Réviser

Vous connaissez celle-là. Elle arrive dans votre file de revue un mardi après-midi : une pull request intitulée « fixes », un diff couvrant 2 347 lignes sur 41 fichiers, aucune description, et un joyeux « PTAL » en commentaire. Le cœur vous tombe. Vous l'ouvrez quand même. Vingt minutes plus tard, vous avez lu la même méthode trois fois, vous n'arrivez toujours pas à savoir quel problème elle résout, et vous avez laissé un seul commentaire nerveux : « ça a l'air bien dans l'ensemble, peut-être renommer cette variable ? » Vous venez de valider du code que vous n'avez pas compris.

L'auteur n'était pas malveillant — il était probablement la tête dans le guidon, fier du travail, et a simplement oublié que livrer du code n'est que la moitié du travail. L'autre moitié consiste à le faire réviser, comprendre et merger en toute sécurité. Une pull request n'est pas une formalité à franchir avant de merger ; c'est une conversation, et comme toutes les conversations, elle se passe mieux quand quelqu'un fait l'effort d'être compris.

Cet article porte sur cet effort : comment écrire des PRs que vos coéquipiers prennent vraiment plaisir à réviser — petites, ciblées, faciles à suivre et faciles à accepter.

Une PR est de la communication, pas seulement du code

Avant une seule ligne de diff, une pull request est un message à un autre être humain. Cet être humain a un temps limité, un contexte limité sur ce à quoi vous pensiez à 23h, et une dizaine d'autres choses qui se disputent son attention. Votre travail en tant qu'auteur est de faciliter son travail.

Pensez au relecteur comme à votre audience, pas à votre juge. Il n'est pas là pour vous piéger — c'est un collaborateur qui vous aide à livrer quelque chose de solide. Plus vous l'aidez à comprendre le pourquoi derrière le changement, plus la revue sera rapide et de qualité. Une bonne description de PR est comme une lettre de motivation pour votre code : elle plante le décor, explique la motivation et dit au relecteur exactement quoi regarder.

Ce changement de mentalité change tout. Une fois que vous arrêtez d'écrire des PRs pour vous-même et que vous commencez à les écrire pour votre relecteur, vous voudrez naturellement les rendre plus petites, les décrire mieux et les soigner avant de demander des regards.

Gardez-la petite et focalisée

La chose la plus efficace que vous puissiez faire pour améliorer vos pull requests est de les rendre plus petites. Plus une PR est grande, moins elle est révisée minutieusement, plus elle prend de temps à merger, et plus de bugs passent au travers.

Une bonne PR contient un seul changement logique. Pas un ticket, pas une fonctionnalité, pas le travail d'un sprint — une idée cohérente qui peut être comprise, testée et annulée indépendamment. « Ajouter l'upload d'avatar utilisateur » est un changement. « Ajouter l'upload d'avatar utilisateur et refactorer le contrôleur de profil et mettre à jour trois dépendances » est trois changements dans un seul manteau.

Comment diviser un grand travail

Les grandes fonctionnalités n'ont pas besoin d'arriver sous forme de grandes PRs. Quelques stratégies de division pratiques :

• Séparez le refactoring des changements de comportement. Première PR : renommer, restructurer, extraire — pas de nouvelle logique. Deuxième PR : la fonctionnalité réelle. Les relecteurs peuvent vérifier que le refactoring n'a pas d'effets secondaires, puis se concentrer entièrement sur la nouvelle logique.
• Livrez l'infrastructure en premier. Ajoutez la colonne de base de données, la migration, le type — tout ça sans aucune interface. Puis ajoutez l'interface qui l'utilise. Chaque PR est déployable indépendamment.
• Utilisez les feature flags. Mergez du travail incomplet derrière un flag désactivé par défaut. La PR est petite et sûre ; la fonctionnalité n'est pas « terminée » avant que vous activiez le flag.
• PRs empilées. La PR B dépend de la PR A. Certaines équipes utilisent des outils de PR empilées pour réviser chaque couche indépendamment. Si votre équipe n'utilise pas l'empilement, restez simple : terminez et mergez A d'abord, puis ouvrez B.

Rédiger un titre et une description qui valent la lecture

Le titre est le titre de l'article. Il doit dire ce qui a changé et pourquoi ça compte, en une ligne. Évitez les verbes vagues comme « mettre à jour », « corriger des trucs », ou « modifications » et visez la spécificité. Voici des odeurs courantes de titre de PR et comment les corriger :

La description est là où la vraie communication se passe. Une bonne description répond aux trois questions que tout relecteur se pose dans les dix premières secondes :

• Quoi a changé et où ?
• Pourquoi ce changement était-il nécessaire — le contexte, le bug, la user story ?
• Comment vérifier que ça fonctionne — étapes de test, captures d'écran, cas limites concernés ?

Voici un avant-après pour rendre ça concret :

--- AVANT (la PR « fixes » de 2 000 lignes) ---

Titre : fixes

Description : (vide)


--- APRÈS (le même changement, rédigé pour un relecteur) ---

Titre : Fix race condition dans le checkout panier sur sessions concurrentes

## Quoi
Deux requêtes de checkout concurrentes du même utilisateur pouvaient toutes les deux
passer la vérification d'inventaire avant que l'une ou l'autre ne décrémente le
compteur de stock, entraînant des surventes. Cette PR ajoute un verrou de ligne DB
autour du décrément du stock.

## Pourquoi
Le support client a signalé 12 incidents de survente au cours des 30 derniers jours
(voir Sentry issue #4421). La cause racine est deux requêtes en concurrence entre le
SELECT et l'UPDATE sur la table d'inventaire.

## Comment tester
1. Lancer le nouveau test de régression de concurrence : npm test -- cart.concurrency
2. En staging : ouvrir deux onglets de navigateur, cliquer sur « Acheter »
   simultanément sur un produit avec stock = 1. Un seul devrait réussir.

## Risques / notes
- Le verrou est limité à une seule ligne produit ; n'affecte pas le débit
  quand différents produits passent en caisse en même temps.
- Pas de migration nécessaire — utilise SELECT FOR UPDATE sur la table existante.

Hygiène des commits

La façon dont vous organisez vos commits compte — pas seulement pour satisfaire le processus, mais parce que les commits sont la trace permanente de comment un changement est venu à exister. Dans un an, quelqu'un (probablement vous) lancera git blame sur une ligne et suivra le hash de commit dans l'historique. Ce qu'il trouvera devrait raconter une histoire, pas ressembler à un flux de conscience.

Un bon message de commit suit le format conventionnel : une ligne de sujet courte à l'impératif (50 caractères ou moins), une ligne vide optionnelle, et un corps optionnel expliquant pourquoi — pas ce que le diff montre déjà.

# Le format conventionnel :
type(scope): sujet impératif court

Corps optionnel : pourquoi ce changement a été fait, quel problème il résout,
les décisions non évidentes et le raisonnement derrière elles.

# Exemples réels :
fix(cart): add row-level lock to prevent oversell on concurrent checkout

feat(auth): add email-change verification flow

refactor(profile): extract avatar upload to dedicated service

Au-delà du format du message, pensez à la forme des commits. Chaque commit devrait représenter une étape cohérente — un refactoring, un test, un nouveau comportement. Un relecteur qui regarde les commits individuels (plutôt que le diff entier) devrait pouvoir suivre la progression logique : « extraire la méthode → ajouter un test → implémenter le comportement » raconte une meilleure histoire que vingt commits « WIP » squashés à la dernière seconde.

Utilisez le rebase interactif pour nettoyer une branche désordonnée avant d'ouvrir la PR. Vous n'avez pas besoin de commits parfaits dès le début — polissez-les avant de demander des regards.

Auto-revue avant de demander la revue

Avant de contacter un coéquipier, devenez votre propre premier relecteur. Ouvrez le diff sur GitHub (ou votre hébergeur de code) et lisez-le comme si vous n'aviez jamais vu le code. Ce changement de contexte détecte plus de problèmes que vous ne l'attendriez : les sorties de débogage oubliées, une fonction qui a trop grossi, un import que vous avez oublié de supprimer, un commentaire qui était vrai autrefois.

Une checklist d'auto-revue qui mérite d'être parcourue :

• Lisez le diff de haut en bas. Ne survolez pas. Faites semblant de le voir pour la première fois.
• Vérifiez les restes de débogage. console.log, commentaires TODO marqués « supprimer », blocs commentés, valeurs temporaires codées en dur.
• Vérifiez que les tests sont là. Si vous avez ajouté de la logique, y a-t-il un test ? Si vous avez corrigé un bug, y a-t-il un test de régression ?
• Cherchez les changements non intentionnels. Agitation des espaces blancs, fichiers reformatés, dérive de portée accidentelle. Déplacez-les dans une PR séparée ou annulez-les.
• Laissez vous-même des commentaires guidants. Si une section n'est pas évidente, ajoutez un commentaire PR expliquant le raisonnement avant que votre relecteur le voie. Ce n'est pas un signe de faiblesse — c'est de la considération.

L'auto-revue rapporte aussi un dividende égoïste : elle détecte les erreurs embarrassantes avant qu'elles ne deviennent des commentaires permanents dans l'historique de revue. Tout le monde a une histoire de la faute de frappe qu'il a repérée dix secondes après avoir appuyé sur « Demander la revue ». Dix minutes d'auto-revue élimine la plupart de celles-là.

Répondre à la revue

Une PR n'est pas terminée quand vous poussez le code — elle est terminée quand elle merge. Entre ces deux événements se trouve le cycle de revue, et la façon dont vous gérez les retours compte autant que le code lui-même.

Quelques principes qui gardent les revues en mouvement et les relations intactes :

• Répondez à chaque commentaire. Même juste pour dire « fait » ou « bon point, corrigé dans le dernier commit ». Le silence laisse les relecteurs se demander si vous avez vu leur note.
• Décrivez votre correctif quand vous le poussez. « Corrigé dans le dernier commit — déplacé la logique dans un helper et ajouté un test » est bien plus clair qu'un nouveau commit sans contexte.
• Résolvez les fils de manière réfléchie. Dans la plupart des équipes, c'est le commentateur qui résout quand il est satisfait. Ne vous auto-résolvez pas sans reconnaître le retour. Si vous n'êtes pas sûr de la convention, demandez.
• Soyez en désaccord avec respect. Si vous pensez qu'une suggestion est fausse, dites-le clairement et avec du raisonnement — ne l'ignorez pas simplement. « J'ai envisagé cette approche, mais [raison] — heureux d'en discuter si vous vous sentez fortement » maintient la conversation professionnelle et productive. Voir aussi : comment réviser le code avec bienveillance pour la perspective du relecteur sur la même conversation.
• Re-demandez la revue explicitement. Après avoir adressé les retours, n'attendez pas que les relecteurs le remarquent. Re-demandez la revue et laissez un court résumé : « Adressé tous les commentaires. Changements principaux : extrait l'utilitaire, ajouté deux tests, gardé l'approche originale pour X parce que Y. »

Comment les normes de PR évoluent selon la taille de l'équipe

Ce qui fait une excellente PR n'est pas fixe — ça évolue à mesure que l'équipe grandit et que la base de code mûrit. Voici comment les attentes évoluent :

Une équipe startup de quatre personnes n'a pas besoin d'un plan de rollback dans chaque description de PR. Une banque en a besoin. Adaptez la cérémonie aux enjeux, et revisitez les normes à mesure que l'équipe grandit — ce qui fonctionnait à dix ingénieurs semblera insuffisant à cinquante.

La prochaine étape est l'autre côté de la table : comment la personne qui reçoit votre PR devrait donner des retours qui aident plutôt que piquent. Si vous avez déjà écrit une PR soigneusement rédigée pour ne recevoir en retour qu'un sec « c'est faux, réécrivez », vous apprécierez Les Retours qui Atterrissent — la suite de cet article.