---
description: How to write comprehensive PR descriptions that help reviewers understand changes
---

# PR Description

Write PR descriptions that help reviewers understand what changed and why.

## Structure

Use this standard structure for PR descriptions:

```markdown
## Summary
<1-3 bullet points of what changed and why>

## Context
<Why this change was needed - the problem being solved>
<Link to related issues/tickets>

## Changes
<Detailed breakdown by area/component>
- Area 1: What changed and why
- Area 2: What changed and why

## Testing
<How this was verified>
- Automated: Tests added/updated, CI status
- Manual: Steps to verify functionality

## Screenshots (if UI changes)
<Before/after screenshots if applicable>
```

## Guidelines

### Lead with WHY, not WHAT
- The diff shows WHAT changed - your description explains WHY
- Start with the problem being solved
- Explain the approach chosen and alternatives considered

### Link to context
- Reference related issues: `Fixes #123` or `Relates to #456`
- Link to design docs or discussions
- Mention dependent PRs if any

### Call out review areas
- Highlight areas needing careful review
- Note any tricky or non-obvious code
- Point out architectural decisions

### Note breaking changes prominently
- Use a dedicated "Breaking Changes" section if applicable
- Explain migration path for consumers
- List any deprecations

### Be scannable
- Use bullet points over paragraphs
- Keep sections focused and concise
- Put the most important info first

## Anti-patterns to Avoid

- Empty descriptions or just "fixes bug"
- Repeating the commit messages verbatim
- Including irrelevant implementation details
- Missing context on why the change was made
- Forgetting to mention breaking changes