pull-requests

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.
• 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