How to Write a Pull Request Description in English

A good pull request description does most of the work of a code review before a single comment gets left — it tells the reviewer what changed, why it changed, and how to confirm it actually works, so they can focus their attention on the code itself instead of reverse-engineering your intent. This guide covers the phrasing that makes a PR description fast to review and easy to trust.

Key Vocabulary

Stating the “what” concisely — a one or two sentence summary of the change itself, written so someone skimming the PR list understands the change without opening the diff. “I stated the what concisely: this PR adds retry logic with exponential backoff to the payment webhook handler.”

Explaining the “why” — the motivation or problem this change addresses, giving the reviewer context for evaluating whether the approach is appropriate. “I explained the why: webhook deliveries were failing silently during brief downstream outages, and we had no retry mechanism at all.”

Describing the approach — a short explanation of how the change works, especially useful when the solution isn’t obvious just from reading the diff. “I described the approach: retries use exponential backoff with jitter, capped at five attempts, to avoid overwhelming the downstream service during an outage.”

Providing a verification path — concrete steps the reviewer (or anyone else) can follow to confirm the change works as intended, whether that’s a test, a screenshot, or manual reproduction steps. “I provided a verification path: run the included test suite, or manually trigger a webhook failure locally using the provided mock server script.”

Flagging risk or scope explicitly — calling out anything unusual about the change’s blast radius, such as touching a shared library or affecting a high-traffic path. “I flagged the risk explicitly: this touches the shared retry utility used by three other services, so I’ve also run their existing test suites against this change.”

Common Phrases

• “This PR [adds/fixes/refactors] [specific thing], because [specific problem or motivation].”
• “Previously, [old behavior]; now, [new behavior].”
• “To verify: [specific steps, e.g. run tests, check this screenshot, reproduce locally with X].”
• “This change is scoped to [specific area] and doesn’t affect [related area].”
• “Note: this depends on [related PR/config change] being merged/deployed first.”

Example Sentences

A complete, well-structured description: “This PR adds retry logic with exponential backoff to the payment webhook handler, because webhook deliveries were failing silently during brief downstream outages with no retry mechanism at all. Retries are capped at five attempts with jitter to avoid overwhelming the downstream service. To verify: run npm test webhook-retry, or use the included mock server script to simulate a transient failure locally.”

Flagging a dependency on another change: “Note: this PR depends on the feature flag added in #4821 being merged first — without it, the retry path is unreachable and this PR’s tests will fail in CI.”

Calling out scope explicitly for a shared utility change: “This touches the shared HTTP client used by both the billing and notifications services, so I’ve run both of their test suites locally against this change and confirmed no regressions.”

Describing a refactor with no behavior change: “This is a pure refactor — extracting duplicated retry logic into a shared utility — with no intended behavior change. All existing tests pass unmodified.”

Professional Tips

• Lead with the what, then the why — reviewers should understand the change’s purpose within the first sentence or two, not after reading the whole diff.
• Always include a verification path, even a simple one like “existing tests cover this” — a reviewer shouldn’t have to guess how to confirm the change works.
• Explicitly note when a change is a pure refactor with no intended behavior change, since that changes what the reviewer should be checking for.
• Flag scope and blast radius for anything touching shared code, since that context changes how carefully a reviewer should look.
• Note any dependencies on other PRs, feature flags, or config changes clearly, so CI failures or confusing local behavior don’t get misdiagnosed.

Practice Exercise

1. Write a two-sentence “what” and “why” summary for a hypothetical bug fix PR.
2. Write a verification path for a PR that isn’t covered by automated tests.
3. Write a sentence flagging that a change touches shared code used by another team.