Pull request description

Write PR descriptions so reviewers understand why the change exists, what changed, and where to look next. Prefer plain language; avoid dumping raw diffs into prose.

When to apply

• User asks for a PR description, MR body, or “what should I put in the pull request?”
• Summarizing work on a branch before opening a PR
• Rewriting a vague or empty PR template into something reviewable

Required sections

Use this order. Omit a section only if it truly adds nothing (e.g. no ticket yet—say “None” or “TBD” in Links & tracking).

1. Summary

One short paragraph: what this PR does in product or technical terms.

2. Context

Background the reviewer needs: prior behavior, constraints, related systems, or user-facing problem. Not a repeat of the diff—explain situation.

3. Why

Motivation: problem being solved, risk being reduced, or requirement being met. If there was an alternative approach, one line on why this one was chosen (optional).

4. What changed

Bullets grouped by area (e.g. API, UI, infra). Call out breaking changes, migrations, or feature flags explicitly.

5. Links & tracking

• Issue / ticket / Linear / Jira (with IDs or URLs)
• Design docs, RFCs, or specs
• Related PRs (stacked or follow-ups)

6. How to test (when applicable)

Steps or checklist so a reviewer can validate behavior locally or in staging.

Markdown template

Copy and fill:

## Summary

[One paragraph: what this PR does.]

## Context

[Why this work exists; what was wrong or missing before.]

## Why

[Motivation and any notable tradeoffs.]

## What changed

- [Area]: [concise bullet]
- …

## Links & tracking

- Ticket: [URL or ID]
- Docs / design: [links]
- Related PRs: [links]

## How to test

1. …
2. …

Quality bar

• Title: Imperative mood, scoped (e.g. Add retry to checkout API), not vague (Fix stuff).
• Scope: Matches the diff; if the PR is large, say so and point to commits or areas.
• Sensitive changes: Security, data, or rollout notes called out in What changed or How to test.

Anti-patterns

• Only listing file names with no explanation
• “WIP” or “misc fixes” as the whole description
• Missing ticket link when one exists