Getting Your PR Merged in Large Open Source Projects

Your pull request has been sitting for three weeks. The CI passes. Your code is clean. So why hasn't a maintainer reviewed it yet?

Contributing to large open source projects feels different from smaller repositories. The bar is higher, the process more formal, and the feedback cycles longer. But it's not mysterious. The maintainers aren't gatekeeping—they're managing complexity at scale. Understand what they need, and your PR gets merged.

We've learned this the hard way at LavaPi, both maintaining internal tools and pushing code upstream to projects like Kubernetes and React. Here's what actually works.

Start Before You Code

The biggest mistake contributors make is opening a PR without agreement on direction. In large projects, a maintainer rejecting your work after you've spent 40 hours on it isn't negligence—it's the system working as intended.

File an issue first

Open a GitHub issue describing the problem or feature. Be specific. Instead of "add support for custom configurations," write:

"The API currently requires all settings to be passed at initialization. This breaks use cases where config changes at runtime. Proposed solution: add a

reconfigure()

Wait for a maintainer to engage. They'll either confirm it's a good direction, suggest alternatives, or explain why it's out of scope. This five-minute conversation saves you weeks.

Check contribution guidelines

Read the CONTRIBUTING.md file. Seriously. Large projects have specific requirements:

• Code style and linting rules
• Test coverage thresholds
• Commit message formats
• Branch naming conventions

Skipping this is the second-biggest mistake. A PR that doesn't follow conventions gets flagged immediately, regardless of code quality.

Make Your PR Easy to Review

Maintainers are bottlenecks. They're reviewing dozens of PRs while maintaining code, triaging issues, and dealing with infrastructure. Your job is to make their review session as efficient as possible.

Keep it focused

One thing per PR. If your branch touches five different systems, split it into five PRs. This isn't bureaucracy—it's how you ensure each change is reviewed properly and can be reverted independently if needed.

bashCopy
# Good: Separate branches for separate concerns
git checkout -b fix/cache-invalidation
git checkout -b feat/metrics-export
git checkout -b docs/api-examples

Write a clear PR description

Include:

1. What: A one-sentence summary of the change
2. Why: The problem it solves or feature it enables
3. How: Your implementation approach
4. Testing: What you tested and how to verify

Example:

codeCopy
**What**: Add exponential backoff to retry logic

**Why**: Current fixed-delay retries cause thundering herd issues under high load.

**How**: Implement `ExponentialBackoff` class with configurable base and max delays.

**Testing**: Added 12 new tests covering edge cases (max retries, jitter, timing). Verified with load test script in `scripts/test_backoff.py`.

Include test coverage

Large projects won't merge code without tests. Not because they're pedantic, but because untested code rots. Write tests first if possible:

typescriptCopy
describe('ExponentialBackoff', () => {
  it('respects max delay ceiling', () => {
    const backoff = new ExponentialBackoff({ base: 100, max: 1000 });
    expect(backoff.delay(15)).toBe(1000);
  });

  it('applies jitter when enabled', () => {
    const backoff = new ExponentialBackoff({ jitter: true });
    const delays = Array.from({ length: 10 }, (_, i) => backoff.delay(i));
    expect(new Set(delays).size).toBeGreaterThan(1);
  });
});

Respond to Feedback Quickly

When a maintainer comments, respond within 24 hours if possible. Make requested changes in new commits (don't force-push and rewrite history until the PR is approved). Leave a comment when you've addressed feedback so they know you're still engaged.

The Bottom Line

Merging a PR into a large open source project isn't about impressing maintainers with brilliant code. It's about respecting their constraints: limited review bandwidth, need for stability, and responsibility to thousands of users. Follow the process, keep changes focused, and make review effortless. Your code gets merged, and everyone benefits.