A pull request template reviewers actually read

A reviewer opens your pull request with a cold brain. They weren't in your head for the last two days. They don't know which file matters, which change is a drive-by cleanup or what could break in production. The description is the only briefing they get.

Most PR descriptions are one line long or a wall of notes the author wrote for themselves. Both slow the review down, because the reviewer has to rebuild your context from the diff. A short template fixes that. Below is one you can drop into your repo, then a set of weak descriptions rewritten line by line.

The template

Save this as .github/pull_request_template.md and GitHub will prefill it on every new PR. GitLab and Bitbucket have similar settings.

Screenshot from GitHub Docs, Creating a pull request template for your repository, CC BY 4.0

## What
A sentence or two describing the change, in plain words.

## Why
The problem, ticket or decision behind it. Link the issue.

## How to test
1. Steps a reviewer can follow locally or on the preview build.
2. What they should see when it works.

## Risks and rollback
What could break, who would notice, and how to undo it.

## Notes for the reviewer
Files to start with, files that are only renames, open questions.

Five headings is enough. Every extra section is one more thing people learn to skip.

Why each section earns its spot

What. This is the line people read in their notification feed. If it says "Refactor," nobody can decide whether to review it now or after lunch. If it says "Move invoice totals into one helper so tax rounding matches on web and mobile," they can.

Why. Code shows how. Only the author knows why. A reviewer who understands the reason can suggest a simpler route, and a future engineer reading git blame will thank you.

How to test. Written steps turn "looks good to me" into a real check. They also catch the bug you'd have found yourself if you'd tried to describe the test out loud.

Risks and rollback. This section makes the author think about failure before merge. One honest sentence here is worth more than a long list of everything that is probably fine.

Notes for the reviewer. A map of the diff. Tell them the 40 changed files are mostly an import rename and the real logic lives in two of them.

Weak descriptions, rewritten sentence by sentence

Here are lines from real PRs with the details swapped out.

Weak. "Fixed the bug."

Better. "Stops the checkout page from charging twice when someone double clicks Pay. The button now disables after the first click and the API ignores a repeat request with the same key."

The first version names nothing. The second names the bug, the cause and both layers of the fix.

Weak. "Some cleanup and refactoring, also updated deps."

Better. "Splits OrderService into OrderReader and OrderWriter with no change in behavior. Bumps date-fns from 2.29 to 2.30 for a timezone fix. The two changes are in separate commits if you'd rather review them apart."

Bundled changes are fine if you say so. Reviewers mind surprises more than size.

Weak. "Should be good to go, tested locally."

Better. "Tested on the preview build with a free account and a team account. Both can export a CSV of more than ten thousand rows without the page freezing."

"Tested locally" tells the reviewer you ran something. The rewrite tells them what, and they can repeat it.

Weak. "Not sure about this approach, thoughts welcome!!"

Better. "I chose a database trigger over an app level hook because two services write to this table. The tradeoff is that the logic is harder to find. If you'd rather keep it in the app, the hook version is in the branch alt-hook."

Uncertainty is useful when it's specific. Say which part worries you and what the other option was.

Weak. "Risk is low."

Better. "If this breaks, new signups won't get the welcome email. Existing users aren't touched. Reverting this PR restores the old behavior, and no migration needs undoing."

Now the on-call engineer knows what a failure looks like and how to get out of it.

Rewriting your own description

You'll notice most fixes above happen one sentence at a time. Read each line and ask what a reviewer would have to guess. Then replace the guess with a fact. When a sentence is accurate but clumsy, it helps to rework a PR description one sentence at a time and compare a few wordings before you pick one.

A few habits keep descriptions honest.

• Write the description before you request review, not after a reviewer asks.
• Keep screenshots or short clips for any visible change.
• Delete template sections that truly don't apply instead of leaving them blank.
• Update the description when the PR changes during review. A stale description is worse than none.

Small PRs need less of this

The best way to make a description easy is to keep the change small. A PR that does one thing needs three lines of what and why. A PR that does five things needs an essay, and nobody reviews essays carefully.

If a description runs long, take that as a hint to split the branch.

For the line in a PR that still reads clumsily after your edit, try it in the Professional profile of Rephrase AI beside your own version, keep every function name and number exactly as you typed it, and then merge the clearer phrasing by hand.