Pull request size

[stalniy]

Summary

The aim of this RFC is to bring attention to the size of pull requests. Large PRs (500–1000+ lines) are slowing down reviews and increasing the risk of unnoticed issues. This is amplified when the number of comments grows, as many changes naturally lead to more questions and follow-up fixes.

To improve review speed and quality, I propose encouraging smaller PRs (~200–300 lines additions/deletions) using guidelines, feature slicing, and bot reminders. Thought we still may have exceptions for big PRs but this should be extremely rare.

Motivation

Reviewing large pull requests (500–1000+ lines) is challenging and time-consuming. These PRs often take longer to review and merge because:

• 🧠 They require reviewers to understand too many changes at once.
• 💬 They lead to a higher volume of comments and follow-up discussions.
• 🐛 The risk of missing issues or introducing regressions increases.
• ⏳ They block other work while waiting for review, slowing down overall delivery.

Encouraging smaller, focused PRs (~200–300 lines) will improve review speed, reduce cognitive load on reviewers, and make it easier for contributors, especially external ones, to get their changes merged faster.

Benefits

• 🏎 Faster reviews – reviewers can focus on smaller, well-scoped changes.
• 🧠 Lower cognitive load – easier to understand the intent and impact of changes.
• 🔄 Quicker feedback loops – authors get feedback earlier, reducing rework.
• 🐛 Fewer bugs – smaller changes are easier to test and less likely to introduce regressions.
• 🪶 Simpler merges – fewer merge conflicts as changes are integrated more frequently.

Drawbacks

• 📦 Potential for more PRs – splitting work could increase the total number of PRs to review.
• 🔗 Dependencies between PRs – smaller PRs may depend on others, requiring careful coordination.
• 🏗 Incomplete features in main – may require feature flags or incremental implementation to avoid breaking changes.
• ⏱ Overhead for authors – more time spent managing multiple branches/PRs.

Recommendations for making smaller PRs

1. Split changes that can be merged independently

   • Do refactoring in separate PRs before adding new functionality.
   • Slice vertically (e.g., backend API changes first, then UI changes).
   • Isolate changes to shared libraries or packages in standalone PRs.
   • Use feature flags to merge incomplete features safely.
   • Apply the graceful degradation principle: deliver part of the functionality first and iterate in follow-up PRs.

2. Avoid dependent PR chains

   • Avoid creating PRs that depend on other unmerged PRs. They are hard to review, increase rebase conflicts, and slow down merging.
   • Instead, find ways to make each PR self-contained and mergeable (look 1).

3. Write clear PR WHY section in PR

   • If PR relates to an issue, then it's enough to have a reference to the issue
   • If PR is unrelated, then we need to have a clear "Why" section

Enforcement

1. GitHub Action check for PR size

   • Add a required GitHub Action that checks the size of each pull request.

   • For PRs exceeding the threshold (> 500 additions), it will leave a warning comment:

     ⚠️ This PR changes ${changed} lines. Please try to keep PRs under 500 lines for faster review.
     Check out our guidelines on how to split work effectively and why this matters.

   • It will be possible to bypass this check with a special label on PR (e.g., "large-pr"). However, when using this label, the PR author must provide a clear explanation in the PR description describing:

     • Why the PR could not be split into smaller parts.
     • Any steps taken to minimize its size where possible.

2. Prioritize smaller PRs in the review process

   • Encourage reviewers to focus on smaller PRs first.
   • In practice, this happens naturally since smaller PRs are easier to review. Making it explicit reinforces the behavior.

[stalniy]

It's possible to check current amount of changes locally with this command:

% git diff --shortstat main...$(git branch --show-current)
 7 files changed, 41 insertions(+), 17 deletions(-)

[stalniy]

maybe we could think of how to warn user at development time

[ygrishajev]

I totally support the proposal. The only thing I find challenging and non-realistic is this:

Avoid creating PRs that depend on other unmerged PRs. They are hard to review, increase rebase conflicts, and slow down merging.

It would block the progress imo. What still makes sense is not to request reviews for dependent PRs. Basically the flow would be:

1. request review for the PR that can be merged into main
2. merge
3. rebase the dependent one
4. request review

[baktun14]

We can just put PRs that depend on other PRs as draft until the depending PR is merged.