How to Write a Concise Pull Request Description in English
Write a clear, concise pull request description in English: the what-why-how structure, summarising changes, helping reviewers, and a reusable PR template.
A pull request description is the cover letter for your code. A good one helps a reviewer understand your change in seconds; a bad one (“fixed stuff”) forces them to reverse-engineer your intent from the diff. Writing clear PR descriptions in English is a high-leverage skill. This guide shows you exactly how.
The Core Structure: What / Why / How
Almost every good PR description answers three questions:
- What does this change do?
- Why is it needed?
- How did you approach it (if non-obvious)?
“What: Adds rate limiting to the public API. Why: We’re seeing abuse from a handful of clients hammering the endpoint. How: Token-bucket limiter in middleware, configurable per route.”
The why is the part reviewers most need and authors most often skip.
Start With a One-Line Summary
The title and first line should make sense on their own in a list of PRs.
| Weak | Strong |
|---|---|
| ”Updates" | "Add rate limiting to the public API" |
| "Bug fix" | "Fix timezone bug in invoice date calculation" |
| "WIP" | "Refactor auth middleware into a reusable module” |
Use the imperative mood — “Add”, “Fix”, “Refactor” — matching git commit conventions.
Writing the Body
Keep it scannable. Reviewers skim before they read.
This PR adds server-side rate limiting to protect the public API.
Changes:
- New
rateLimitmiddleware using a token-bucket algorithm.- Configurable limits per route in
config/limits.ts.- Returns
429 Too Many Requestswith aRetry-Afterheader.
Bullet points for changes are far easier to review than a paragraph.
Helping the Reviewer
Tell the reviewer where to focus and how to verify.
“The key file to review is
rateLimit.ts— the rest is wiring.” “I’m not sure about the default limit of 100/min; feedback welcome.” “To test locally: run the API and hit/api/searchmore than 100 times in a minute.”
Phrases that guide reviewers:
- “The main change is in…”
- “I’d particularly like feedback on…”
- “This can be reviewed commit by commit.”
Flagging Things Clearly
| Phrase | Meaning |
|---|---|
| ”Draft / WIP” | Not ready for full review yet. |
| ”Ready for review” | Please review now. |
| ”No functional change” | Refactor or formatting only. |
| ”Depends on #482” | Don’t merge before that. |
| ”Breaking change” | Requires coordination. |
“Note: this is a breaking change to the API response format — the mobile team needs to update before we deploy.”
Keeping It Concise
A description should be as long as it needs to be and no longer.
- Don’t restate the diff line by line — the reviewer can read code.
- Do explain anything the diff can’t show: intent, alternatives rejected, context.
“I considered doing this client-side but chose the server to prevent bypass.”
That one sentence saves a round of review questions.
Linking Context
Always link the ticket and any relevant discussion.
“Closes JIRA-482. Design discussion in the #api channel thread.”
Using “Closes” or “Fixes” with an issue number auto-links and often auto-closes the issue on merge.
A Reusable Template
## What Brief summary of the change.
## Why The problem this solves or the value it adds.
## How Approach and any notable decisions.
## Testing How you verified it / how a reviewer can.
## Notes Breaking changes, follow-ups, things you’re unsure about.
Closes #___
Before You Hit “Create”
- Does the title make sense on its own?
- Have you said why, not just what?
- Have you pointed the reviewer to the key files?
- Have you linked the ticket?
- Have you flagged any breaking changes?
A concise, well-structured PR description is a small act of generosity that speeds up the whole team. Lead with what and why, list your changes as bullets, guide the reviewer to what matters, and link the context. Do this consistently and your PRs will get reviewed faster, merged sooner, and remembered as the ones that were a pleasure to read.