A pull request with an empty description is a small act of unkindness to its reviewer. They have to reconstruct the intent from the diff, guess at the testing, and ask questions the author could have answered in thirty seconds. Teams fix this with a template - then often ruin it by making the template a questionnaire nobody reads.
What a template is for#
Drop a file at .github/pull_request_template.md (or .gitlab/merge_request_templates/Default.md) and every new pull request starts with its contents pre-filled. The author’s job shifts from “write something from nothing” to “fill in the blanks” - which is a much lower bar, and that is the whole point.
The sections that earn their place#
Three prompts cover almost everything a reviewer needs:
## What
One or two sentences: what does this change do?
## Why
What problem does it solve? Link the ticket if there is one.
## How tested
What did you run, click, or deploy to staging to convince yourself?
“What” and “why” are the difference between a review and an interrogation. “How tested” is the one authors skip when there is no prompt, and the one that catches “I did not actually run it” before the reviewer does.
For risky changes, one optional line helps: **Risk:** what breaks if this is wrong? Leave it in the template as a comment or optional heading, and the answer doubles as your rollback plan - which pairs well with the habits in rollback or roll forward.
What to leave out#
Every field you add is a tax on every pull request. Skip:
- Long checklists of things CI already checks. “Tests pass” is a status badge, not a checkbox.
- Legalistic boilerplate. Nobody has ever been protected by “I confirm I have read the contributing guide.”
- Sections that only apply to one pull request in fifty. Database migration notes, screenshots, API changes - authors will add these when relevant. A heading they must delete is friction, not help.
If a section is empty on most merged pull requests, cut it.
Keep it alive#
A template is a living document with exactly one success metric: do merged pull requests have useful descriptions? Skim the last ten. If “How tested” is always “yes”, sharpen the prompt (“what command did you run?”). If a section is always deleted, remove it.
The template is also a forcing function for smaller work: a pull request too big to describe in two sentences is a pull request that should be split, which is exactly the argument in small pull requests get reviewed faster. And when the description is written, the advice in writing a good pull request description makes it land.
Start with three headings and resist every addition. The best template is the one nobody notices.
Share this post
Keep reading
A First CI Pipeline for a Laravel Project
Install, lint, test, build - four jobs that run on every pull request and turn 'works on my machine' into a check everyone can see.
A Staging Environment Worth Having
Staging only catches what it shares with production. Same deploy path, same services, sanitized data - and a clear rule for what it is for.
Branch Naming Conventions That Scale Past Three People
Branch names are a user interface for your team's work. The conventions that survive growth, the ones that collapse, and why boring always wins.
