How to Write a Pull Request Description

A pull request description should answer three questions before the reviewer opens the diff: what problem this solves, what approach you took, and where you want them to look hardest. The code shows what changed. Only you can explain why, and why is where most review time is actually spent.

The payoff is asymmetric. Two minutes of writing routinely saves twenty minutes of review, and it saves the round trip where a reviewer asks a question you could have answered upfront.

The Structure

What: Adds retry with exponential backoff to the payment webhook handler.

Why: We are dropping roughly 30 webhooks a day when the provider has brief outages. Those become manual reconciliation tickets for support. Ticket PAY-441.

Approach: Retries up to five times with backoff from 1s to 16s, then writes to a dead letter table for manual review. Chose backoff over a queue because the volume is low and adding a queue means adding infrastructure we would then have to run.

Look at: The idempotency check in handler.ts:88. If the provider sends a duplicate during a retry window I believe we handle it, but I would like a second pair of eyes on that path.

Testing: Unit tests for the backoff schedule. Manually tested against the provider sandbox by forcing a 503. Not tested against a real outage.

Not in this PR: Alerting when the dead letter table grows. Follow-up in PAY-449.

Every section earns its place. Why justifies the change. Approach explains a decision the diff cannot show, including the alternative you rejected. Look at directs attention to the risky part. Testing sets expectations honestly. Not in this PR prevents review comments about scope you already thought about.

Explain the Rejected Alternative

This is the highest-value sentence in most PR descriptions and the one most often missing.

Reviewers cannot see what you considered and discarded. Without that, a sensible-looking suggestion arrives, you explain why it does not work, and both of you have spent time on a conversation the description could have prevented.

One clause is enough. “Chose backoff over a queue because the volume is low” preempts the entire exchange.

Direct the Review

Not all parts of a diff deserve equal attention. A 400-line PR that is 350 lines of generated types and 50 lines of business logic should say so, or the reviewer will skim uniformly and miss the part that matters.

Say what you are unsure about. Admitting “I am not confident about the concurrency here” gets you a genuinely useful review. Presenting everything as finished gets you a rubber stamp and a bug next month.

Keep Them Small

No description rescues a 2,000-line pull request. Review quality collapses past a few hundred lines of meaningful change, and the honest failure mode is approval without real reading.

If a PR is genuinely large, say why in the description, point to the commit sequence, and suggest a review order. Reviewing commit by commit is much easier than reviewing a combined diff when the commits are coherent.

Write for Six Months From Now

PR descriptions become the archaeology record. When someone runs git blame on a strange line in eighteen months, they land on the commit, then the PR, and your description is the only explanation of intent that exists.

Which means: link the ticket, but do not rely on it. Ticket systems get migrated and links rot. Put the actual reason in the description in one sentence.

Write it so someone unfamiliar with the current sprint can understand it. Avoid shorthand that only makes sense this week.

The Fast Version

A Wrivio Context for this could say:

Rewrite these notes as a pull request description with the headings What, Why, Approach, Look at, Testing, and Not in this PR. Neutral technical register, concise, no filler. Convert my rough reasoning into a clear statement of the problem and the decision. If I mentioned an alternative I rejected, include it under Approach with the reason. Keep every file path, line number, ticket reference, and figure exactly as written, and do not claim testing that is not in my notes.

Press Ctrl+Shift+Space over your editor, paste the two lines you scribbled while working, and run it. That last constraint matters: a description that claims integration test coverage you did not write is a genuine problem, and it is exactly the kind of plausible completion a rewrite will produce if you do not forbid it.

What to Leave Out

Do not narrate the diff. “Changed the function to accept a second parameter” is visible in the code and adds nothing.

Do not apologize for the code. If it needs an apology, it needs another commit.

Do not paste large logs. Link them or collapse them.

Common Questions

Does a template help?

Yes, considerably. A repository PR template with these headings raises the median description quality more than any amount of asking people to write better ones.

What about tiny PRs?

A one-line typo fix needs one line. Match the description to the risk, not to a fixed format.

Should the PR title match the commit message?

Usually yes, if you squash. Write it as an imperative summary of what the change does.

Should AI write the description?

For structure and phrasing, useful. For the why and the rejected alternatives, no. That knowledge only exists in your head, and it is the part that has value.

Download Wrivio for Windows to turn scratch notes into a structured PR description without leaving your editor.