Writing Clear Pull Request Descriptions in English
A practical guide to writing clear pull request descriptions in English: structure, phrasing, verb tense, and before/after examples that get your PRs reviewed faster.
A pull request (PR) description is the cover letter for your code. Reviewers decide how to read your diff based on what you write at the top. A clear description gets your PR merged faster; a vague one gets it sitting in the queue for days. For non-native English speakers, the good news is that PR writing follows a predictable structure with reusable phrases.
The standard structure
Most teams expect four sections, even if the template doesn’t enforce them:
- What — what this PR changes (one or two sentences)
- Why — the problem or motivation
- How — the approach you took
- Testing — how you verified it works
You don’t need headings for a small PR, but for anything non-trivial they help reviewers scan.
Section 1: What — use present tense, imperative or descriptive
The title and summary describe what the PR does, not what you did. English convention here is the present simple, often in the imperative mood (matching commit-message style).
Title: Add retry logic to the payment client
This PR adds exponential backoff to the payment client so transient failures are retried automatically.
Avoid past tense narration like “I added retry logic and then I tested it.” Reviewers care about the current state of the code, not your personal history.
| Weak | Strong |
|---|---|
| ”I have made some changes to the auth." | "Refactors the auth middleware to support token rotation." |
| "This is for fixing the bug." | "Fixes the race condition in the session cache.” |
Section 2: Why — give reviewers the context
The why is what reviewers value most. Without it, they can’t judge whether your solution is right. Link to the issue and state the problem in plain terms.
Why: Users on slow connections occasionally see duplicate charges because the client doesn’t deduplicate retries. This resolves issue #482.
Useful phrasing:
- “This addresses a long-standing problem where…”
- “The root cause is that…”
- “Previously, X would happen whenever…”
- “This unblocks the migration work in #501.”
“Previously, the worker would silently drop messages when the queue was full. This PR makes the failure explicit.”
Note the use of would for past habitual behaviour — natural and precise for describing recurring bugs.
Section 3: How — explain non-obvious decisions
Don’t restate the diff line by line; reviewers can read code. Instead, explain choices they can’t see.
How: I opted for a token-bucket limiter rather than a fixed window because it handles bursts more gracefully. I deliberately left out the metrics wiring to keep this PR focused — that’ll come in a follow-up.
Phrases for explaining decisions:
- “I opted for X over Y because…”
- “I deliberately left out Z to keep the scope small.”
- “This is intentionally a bit conservative — happy to loosen it later.”
- “I went back and forth on naming; open to suggestions.”
Calling out what you didn’t do is a sign of senior-level communication. Out of scope is the key phrase:
“Renaming the legacy fields is out of scope for this PR.”
Section 4: Testing — be specific
“Tested locally” tells a reviewer nothing. State what you ran and what you observed.
Testing: Added unit tests for the backoff calculation. Ran the integration suite locally — all green. Manually verified against the staging gateway by forcing a 500 and confirming three retries.
Useful verbs: verified, confirmed, reproduced, exercised, covered.
“I reproduced the original bug on
main, then confirmed it no longer occurs on this branch.”
Asking for the review you actually want
Tell reviewers where to focus. This is courteous and speeds things up.
- “The main thing I’d like eyes on is the locking logic in
cache.go.” - “Feel free to skim the generated files — the real change is in three files.”
- “This is ready for review / still a draft / a work in progress (WIP).”
“Heads up: the diff looks large, but most of it is a vendored dependency. The actual change is ~40 lines.”
Before and after: a full rewrite
Before:
“fixed the thing. please review. I think it works now but not sure. there was a problem before.”
After:
Fix duplicate charges on retry
What: Adds idempotency keys to the payment client.
Why: On flaky connections, retries created duplicate charges (#482). The client had no way to tell the gateway “this is the same request.”
How: Each request now carries a UUID idempotency key, generated once and reused across retries. I opted for client-generated keys so we don’t need a round trip.
Testing: Unit tests for key reuse; manually forced retries against staging and confirmed a single charge.
The main thing I’d like eyes on is the key-lifetime logic in
client.py.
Common mistakes
- Vague titles. “Update code” or “fix bug” forces reviewers to open the diff to learn anything. Lead with a verb and an object: “Add”, “Fix”, “Refactor”, “Remove”.
- Past-tense walls of text. Keep the summary in present tense and short.
- No “why”. The single most common reason PRs stall is that the reviewer doesn’t understand the motivation.
- False modesty. “Not sure if this is right” invites doubt. Instead: “I’d appreciate a second opinion on the locking approach” — confident and open.
A reusable template
## What
One-sentence summary in present tense.
## Why
The problem this solves. Link the issue.
## How
Non-obvious decisions and trade-offs. What's out of scope.
## Testing
What you ran and what you observed.
## Review notes
Where to focus. Anything reviewers should skim.Key takeaways
- Use present tense for what the PR does; would for past recurring bugs.
- Always include the why — it’s what reviewers need most.
- Explain decisions and call out what’s out of scope.
- Be specific in testing: name what you ran and observed.
- Direct the reviewer’s attention with “the main thing I’d like eyes on is…”.
A good PR description is empathy in writing form. Spend three extra minutes on it and you’ll save your reviewers thirty.
Navigating Nuances: Refining Your Approach for Non-Native Speakers
Let’s be honest – communication across cultures and language levels can be tricky, even within a well-intentioned team. As developers, we often assume everyone understands the technical context of our work, but that assumption can create friction during code reviews and pull request discussions. For non-native English speakers, particularly those transitioning into professional development environments, subtle differences in phrasing and verb tenses can lead to misunderstandings and delays in getting feedback. It’s not about expecting perfect grammar; it’s about striving for clarity and proactively addressing potential barriers to understanding.
One common issue is the use of overly formal or technical language that isn’t immediately accessible. Imagine receiving a comment like, “The implementation deviates from established architectural paradigms.” While technically accurate, it’s dense and doesn’t clearly explain why the deviation needs attention. Instead, try something more direct: “This change introduces a slightly different approach to data handling. Could we discuss the implications for maintaining consistency with our existing system architecture?” Notice the addition of “slightly” – softening the language – and framing it as a discussion rather than an immediate problem. Similarly, phrases like “I have reverted this commit due to… ” can sound abrupt. A more gentle introduction might be: “To ensure alignment with project standards, I’ve reverted this commit. Let’s discuss the rationale behind the original change.”
Another area of focus should be around expressing intent. Instead of simply stating what was done (“I added a new function”), describe why it was added and its intended purpose (“I implemented a new function to streamline data processing, reducing potential errors in subsequent calculations”). This provides context for reviewers to quickly grasp the value of the change. Don’t be afraid to use phrases like “To improve…” or “This addresses…”.
Finally, remember that concise communication is key. While detail is important, avoid unnecessary jargon and overly complex sentences. Prioritize conveying the core information efficiently. A good PR description doesn’t need to be a novel; it needs to be a clear roadmap for the reviewer to understand your work’s purpose and impact. Being mindful of these nuances will not only help non-native speakers but ultimately improve communication across your entire team.