Skip to content
Antoine Le LouëtIndependent senior developer (Home)
Back to the Journal

Advice3 min read

Prepare a pull request that is easy to review

Someone discovering your pull request should be able to understand the problem and verify the fix. Here is how to provide that context.

A diff adds the Advice category to a pagination link. A note explains the lost filter and identifies the checked flow: page 2, then back.
The PR connects a focused fix to its problem: preserve the category filter when changing pages.

Start with the problem being solved

The person reviewing a pull request may not have followed the discussion that prompted it. A useful description therefore starts with current behaviour and the expected result. ‘Preserve the filter when moving to the next page’ gives them an intention that is easier to verify than a list of changed files.

A before-and-after example may be enough. With a category selected, the pagination link used to lose that filter; it should now preserve it. The reader can connect the code change to a concrete case, then look for boundaries: first page, last page, no filter or an invalid value.

Keep a scope you can explain

It is tempting to use a fix as an opportunity to reformat a module or rename its components. Those changes may be useful, but they make the diff longer to examine. I prefer each change to contribute to the described problem, or to be clearly justified as a necessary prerequisite.

  • Choose a title that describes the result for the project.
  • Exclude generated files and unrelated formatting changes.
  • Explain trade-offs that might surprise the reader.
  • Identify migrations, settings or launch steps that are actually needed.

Provide a way to verify

The commands executed form part of the evidence, together with their results. For a visible change, a short manual flow usefully complements tests: open a URL, select a category, change pages, then go back. A screenshot can show layout, but it does not replace this behavioural check.

Example description
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.

A command that was not run must not be presented as successful. If verification is blocked by the environment or missing access, describing the obstacle precisely lets the reviewer take over. That information is more actionable than simply saying ‘to be tested’.

Make discussion and corrections easier

A good review may simplify the solution or refine an edge case. Context and verification must therefore stay up to date after corrections. The final description presents the proposed change to the next reader; it does not need to recount every abandoned attempt.

Share on LinkedIn (new tab)

Keep reading
All articles in this category