pull-request-conventions

Pull request conventions

A PR description is written for the reviewer. Its job is to make the change easy and fast to review correctly. Optimize for their time, not for completeness theater.

Structure

Use only the sections that carry signal:

• Summary — what changed and why, in 2–4 sentences. The why goes first; the diff already shows the what.
• Changes — notable changes as a short bulleted list, grouped by theme. Not a file-by-file restatement of the diff.
• Testing — how it was verified, or exactly what the reviewer should check. Be honest: if something wasn't tested, say so.
• Notes — risks, known limitations, follow-ups, or explicitly out-of-scope items. Omit the section entirely if there are none.

Tone

• Lead with why. Reviewers can read the diff for the what; they can't read your mind for the why.
• Scannable beats thorough. Short bullets, clear headings, no walls of prose.
• Proportional. A one-line fix gets a one-line description. Don't inflate.
• Honest. Never claim testing that didn't happen. Flag the risky parts rather than burying them.
• American English, present tense, active voice.

Anti-patterns

• Restating every file in the diff as a bullet.
• "Various fixes and improvements" — say which, and why.
• A long Testing section that just says "tested locally" with no specifics.
• Hiding a breaking change three paragraphs down instead of calling it out up top.