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