Préparer une pull request facile à relire

Commencer par le problème que l’on résout

La personne qui relit une pull request n’a pas forcément suivi la discussion qui l’a déclenchée. Une description utile commence donc par le comportement actuel et le résultat attendu. « Conserver le filtre lorsque l’on passe à la page suivante » lui donne une intention plus facile à vérifier qu’une liste de fichiers modifiés.

Un exemple avant/après peut suffire. Avec une catégorie sélectionnée, le lien de pagination perdait ce filtre ; il doit désormais le conserver. Le lecteur peut alors relier le changement de code à un cas concret, puis rechercher les limites : première page, dernière page, filtre absent ou valeur invalide.

Garder un périmètre que l’on peut expliquer

Il est tentant de profiter d’une correction pour reformater un module ou renommer ses composants. Ces changements peuvent être utiles, mais ils rendent la différence plus longue à examiner. Je préfère que chaque modification contribue au problème décrit, ou qu’elle soit clairement justifiée comme un préalable nécessaire.

• Donner un titre qui décrit le résultat pour le projet.
• Écarter les fichiers générés et les changements de format sans rapport.
• Expliquer les compromis qui pourraient surprendre le lecteur.
• Signaler les migrations, les paramètres ou les étapes de mise en service réellement nécessaires.

Donner une manière de vérifier

Les commandes exécutées constituent une partie de la preuve, avec leurs résultats. Pour une évolution visible, un parcours manuel court complète utilement les tests : ouvrir une URL, sélectionner une catégorie, changer de page puis revenir en arrière. Une capture peut montrer la mise en page, mais elle ne remplace pas cette vérification du comportement.

Problème
Le filtre disparaît lorsque l’on change de page.

Résultat
Les liens conservent la catégorie dans leur URL.

Vérification
Sélectionner Conseils, ouvrir la page 2, revenir en arrière.

Limite
Les cas non vérifiés sont indiqués explicitement.

Une commande qui n’a pas été lancée ne doit pas être présentée comme réussie. Si une vérification est bloquée par un environnement ou un accès manquant, la décrire précisément permet au lecteur de prendre la suite. Cette information est plus exploitable qu’un simple « à tester ».

Faciliter la discussion et les corrections

Une bonne revue peut conduire à simplifier la solution ou à ajuster un cas limite. Le contexte et les vérifications doivent donc rester à jour après les corrections. La description finale présente le changement proposé au lecteur suivant ; elle n’a pas besoin de raconter toutes les tentatives abandonnées.