Skip to content
Toprent.app Docs

5. [PROPOSAL] Pull request size limits

Date: 2025-10-01

Status

Proposed

Context

Large pull requests create multiple problems:

  • Harder to review - Reviewers struggle to maintain focus and catch issues in PRs with hundreds of lines changed
  • Slower to merge - Large PRs take longer to review, increasing time to production
  • Higher risk - More changes mean more potential for bugs and unintended consequences
  • Difficult to revert - If something goes wrong, reverting a large PR can be painful
  • Context switching - Reviewers need significant uninterrupted time to properly review large changes
  • Merge conflicts - Large, long-lived PRs are more likely to conflict with other work

We need guidelines on appropriate PR size to maintain code quality and review efficiency.

Decision

Ideal PR size: 200-400 lines of code changed

This is a guideline, not a hard rule. The goal is to keep PRs focused and reviewable.

Guidelines:

  • Target: Keep most PRs under 400 lines changed
  • Good: 200-400 lines - easy to review in one sitting
  • Acceptable: 400-800 lines - still manageable with focus
  • Too large: 800+ lines - strongly consider breaking it up

When PRs must be larger:

Some changes are inherently large (refactoring, migrations, generated code, POCs). In these cases:

  1. Explain why in the PR description
  2. Break it into logical commits that tell a story
  3. Add detailed comments explaining complex changes
  4. Consider splitting into multiple PRs if possible (e.g., refactor first, then new feature)
  5. Give reviewers a heads-up that this will take more time

How to keep PRs small:

  • One concern per PR - Don’t mix refactoring with new features
  • Use feature flags - Ship incomplete features behind flags
  • Break down tickets - Split large tickets into smaller, deliverable chunks
  • Separate prep work - Do refactoring/cleanup in a separate PR first
  • Avoid scope creep - Resist the urge to “fix nearby code” in the same PR

Consequences

Positive

  • Faster, more thorough code reviews
  • Reduced time from code completion to production
  • Easier to identify and revert problematic changes
  • Reduced reviewer fatigue and better review quality
  • Encourages better ticket breakdown
  • Reduces merge conflicts

Negative

  • Requires more discipline and planning
  • May need to use feature flags or incremental delivery
  • Some engineers may find it constraining
  • Requires breaking down work more thoughtfully

Neutral

  • Shifts focus from “completing features” to “shipping incremental value”
  • Creates more PRs but each is easier to handle
  • Encourages thinking about deployability and rollback

Review Schedule

Review after 3 cycles to assess:

  • Are PRs generally smaller and easier to review?
  • Is code review happening faster?
  • Are we using feature flags effectively for incremental delivery?
  • Do we need to adjust the size guidelines?