---
name: pull-requests
description: Read when opening a pull request, writing a PR description, splitting work into PRs, or deciding whether a change is too large to review. Covers the size targets, the one-purpose-per-PR rule, what makes a PR reviewable on its own, and the exceptions for dependency bumps, codemods, migrations, and generated files.
---

# Pull Request Guidelines

Break changes down into small, focused pull requests that can be easily reviewed.
As a rule of thumb, a PR should be reviewable in under 15 minutes.

## Guidelines

### 1. Keep PRs Small

- Ideal PR size is under 100 changed lines. Under 200 lines is usually acceptable. Larger
  changes should be split into multiple PRs unless there is a reason not to.
- It is okay to have a larger PR if it is mostly mechanical changes, such as generated files, test
  data, or formatting. But the core PR logic should ideally remain under 100 lines.
- Use stacked PRs to work on larger features without being blocked by review.

### 2. One Purpose Per PR

- A pull request should do one thing only. Do not mix unrelated changes in the same PR.
- Minor improvements to the neighborhood of the main change are ok, but larger refactors
  should be in a separate PR.

### 3. Every PR Must Be Reviewable on Its Own

A reviewer should be able to understand what changed, why, and how it was validated. That usually
means:

- In the code
   - clear comments for non-obvious logic
   - TODO comments for future work
   - tests for new behavior when appropriate
   - updated docs when user-facing behavior changed
   - no unrelated formatting or cleanup noise
- In the PR on GitHub
   - clear PR description
   - screenshots or recordings for UI changes
   - line comments for non-obvious code changes

In some cases, the tests or a docs change may be in a separate PR if it would be too large to
review together.

### 4. Description & Suggested Reviewers

- Follow `.github/pull_request_template.md`. Keep the description short and human readable.
- Propose a few short bullet points that say which problem the PR addresses and how it is solved.
  Write them so that a reader who does not know the code can follow.
- Assign the reviewer most likely to help, based on `git blame`/`git log` history of the touched
  files or lines, and recommend an alternative one at the end of the description.
- For a stack of PRs, prefer the same reviewer(s) for each item in the stack, unless the items
  can be reviewed independently.

## Exceptions

Some PRs will not fit the normal shape. Examples:

- dependency upgrades
- mechanical codemods
- large test updates
- schema or migration changes
- generated files

In those cases, optimize for reviewer clarity:

- explain why the PR is large
- separate mechanical and logical changes where possible
- call out risk areas explicitly