A pull request description isn’t for you. It’s for the person reviewing your code. Their job is to verify that the changes are correct, safe, and complete. Your job is to make that as easy as possible.
A PR with no description forces the reviewer to reverse-engineer your intent from the diff. That’s slow, error-prone, and frustrating for everyone involved.
When you need this#
- Code reviews take too long because reviewers don’t understand the context of the changes.
- PRs get approved without meaningful review because the diff is too big to reason about without guidance.
- Engineers merge changes that don’t link back to a ticket, making it hard to trace why something was changed.
What each section is for#
Background - Why does this PR exist? Link to the ticket. If the ticket doesn’t tell the whole story (maybe the implementation approach diverged from what was planned), explain the technical context here. The reviewer should understand the “why” before they look at a single line of code.
Changes - A bullet list of what you changed, in plain language. Not a commit-by-commit replay. Think of it as a map of the diff: “Added a new endpoint for X, refactored Y to support Z, removed the old migration.” This tells the reviewer where to focus.
Screenshots - If the change has a visual component, show it. Before and after screenshots make UI changes trivial to review. Remove this section entirely if the change is backend-only; an empty screenshots section just adds noise.
TODO - Anything that’s unfinished or needs follow-up. This is especially useful for draft PRs. If there are open questions, flag them here so the reviewer knows what’s settled and what’s still in flux.
Fixes #123 or equivalent. This creates a two-way link: the PR points to the ticket for context, and the ticket points to the PR for implementation details. Six months from now, when someone asks “why did we change this?”, that link is the answer.The template#
## Background
<!--
Explain any background of why this PR is being made. Often a link to the main
issue is enough, but you may need to elaborate on it to explain something
technical.
Fixes #{ticket_number}
-->
## Changes
<!-- A bullet list summarizing the changes you have made. -->
* TBD
## Screenshots
<!-- Remove if not relevant -->
## TODO
<!--
Any items that need to be resolved still.
Also, evaluate if a "Draft" PR and adding the "Work in Progress" label is
appropriate.
- [ ] Make sure to notify developers of change
- [ ] Figure out what fixtures are necessary
-->