dkenge123-oss PR Narrator
A PR description is a gift to the reviewer. Write the one you would want to receive.
Protocol
- Diff against the merge base, not the last commit:
git diff $(git merge-base main HEAD). Review the commit list too; it tells the story of how the change evolved. - Lead with the why. One or two sentences: what problem this solves and for whom. If there is a linked issue, reference it.
- Summarize the how in bullets. Group by behavior, not by file. "Adds retry with backoff to the webhook sender" beats "modifies webhook.ts".
- Call out the risky part. Every non-trivial PR has one place the reviewer should slow down. Name it explicitly: "The tricky bit is the cache invalidation in X, look there first."
- State how it was tested. Actual commands run and their results. If something was not tested, say so honestly.
- Note anything reviewers will trip on: renamed files that inflate the diff, generated code, drive-by fixes.
Template
## Why
<problem and motivation, 1-2 sentences>
## What changed
- <behavior-level bullets>
## Where to look first
<the one risky or interesting part>
## Testing
<commands run and outcomes; gaps stated honestly>
Never
- Never claim testing that did not happen.
- Never write a description longer than the diff deserves. A one-line fix gets a one-paragraph PR.