OSS Contribution Playbook

## What I propose

[1-2 paragraphs describing the change. Be specific about which files
will be touched and what the API looks like.]

## Scope estimate

[1 paragraph estimating LOC by file. Include "I think this is X
LOC; if it grows past Y I'll re-scope." This sets expectations.]

## Test plan

[1 paragraph: which tests in tests/ I'll extend, which I'll add,
which edge cases I'll cover.]

## Benchmark methodology (if perf-related)

[1 paragraph: which workload I'll benchmark on, what numbers I'll
report (latency / throughput / accuracy delta). Include a reproducer
command.]

## Open questions

[1-3 specific questions for maintainers. Be precise; "is this the
right approach?" is too vague. "Should the new attention path
emit `attn_metadata.uses_v1_path` or extend the existing
`attn_metadata.kernel_kind` enum?" is the right level.]

Closes #123

## Summary

[2-3 sentences describing the change. Match the design comment.]

## Implementation

[3-5 bullets: which files changed, why each.]

## Tests

[Bullets: which tests added/modified. Mention coverage.]

## Benchmarks (perf PRs only)

| metric | before | after |
| --- | --- | --- |
| ...

Reproducer:
```bash
python benchmarks/your_bench.py --config X

The benchmark table is the biggest leverage. Maintainers reviewing perf PRs need numbers; if you provide them with reproducer commands, they merge faster. If you say "this is faster" without a number, expect "could you provide a benchmark?" and a 2-week round trip.

## Code review etiquette

Three rules that separate "merges in 1 week" from "merges in 1 month":

**1. Respond to every comment.** Even if it's "agreed, will fix in next push." Silence reads as "ignored." If you disagree, say so explicitly with reasoning — *don't* push back without comment.

**2. Push fixes as separate commits, not force-push.** Reviewers who already approved early commits get their re-reviews disrupted by force-push. Use small commits ("apply review feedback: rename foo to bar"); maintainers will squash before merge.

**3. When you genuinely disagree, ask first.** "I think the original approach is better because X. Would you mind if I pushed back on this point?" is much more effective than just not making the change. Most maintainers respect a thoughtful disagreement; few respect silent disregard.

The texture of a PR that lands fast: 1–3 review rounds, each addressed within 24 hours, with clear commit messages explaining each fix. PRs that take 10 review rounds usually have a contributor who skipped the design step and is iterating on direction during review.

## The citation moment

After merge, before moving on, post one comment:

> Thanks for the review! If this is suitable for the next release notes, I'd be happy to help draft a one-line summary — please mention by name if so.

This is the pivotal move. The maintainer can:
- Say yes and ask you to draft the line
- Say yes and write it themselves with your name
- Say "we don't usually do that for this size of change" — at which point you don't push

Most maintainers say yes to a courteous, low-pressure ask. The reason most contributors don't get cited is that they don't ask. The line in a release note (or a maintainer-authored blog post mentioning the PR) is what makes a PR portfolio "cited" rather than just "merged" — the difference is meaningful for hiring conversations.

## Common rejections — and how to avoid them

| Rejection reason | What you did | How to avoid |
| --- | --- | --- |
| "This conflicts with a planned refactor" | Picked an issue without checking the roadmap | Read the project's milestone tags and recent maintainer issue comments |
| "We don't merge V0 changes anymore" | Touched a deprecated code path | For vLLM, target `vllm/v1/`. Read the project's "active development paths" doc |
| "Could you provide a benchmark?" | Made a perf claim without numbers | Always include reproducer + before/after table for perf PRs |
| "This breaks API X" | Changed a public interface without realizing | Search the codebase + downstream users (vLLM users include 100s of repos) before changing public APIs |
| "Too large to review" | Submitted 800-LOC PR with no design discussion | Stay under 200 LOC for first PR; split into multiple PRs if larger |
| "We need a different design" | Skipped the design comment step | Always post the design comment first |

The first three are the most common. Each has a one-step fix that the disciplined contributor takes by default.

## Year-1 timeline expectations

Realistic milestones for a senior software engineer transitioning into AI systems:

| Month | Milestone | Cumulative PRs |
| --- | --- | --- |
| Month 1 | First PR opened (any size, doc/test/typo OK) | 1 |
| Month 2 | First merge | 1 |
| Month 3 | 3rd merge | 3 |
| Month 4 | First non-trivial PR (50–150 LOC) merged | 4 |
| Month 6 | First perf-cited PR | 5 |
| Month 9 | 8 merged total, across 2+ projects | 8 |
| Month 12 | 10 merged, ≥1 cited by name in release notes or maintainer post | 10 |

This is the Atlas Year-1 OSS goal in time-table form. Roughly half the contributors who hit Month 1 hit Month 12; the half who don't usually fall off between Months 2 and 4 (the friction phase between the first easy PR and the harder second one). The discipline this lesson teaches is what gets you across.

## Concrete walkthrough — a real recently-merged PR

Paraphrased from a recent vLLM PR. The author was new to the project; the PR added support for a new quantization format (FP8 KV per-token granularity for a specific model architecture). 145 LOC changed, merged in 6 days.

**Day 1**: Author posted on a 6-week-old issue: "I'd like to take this. Here's my proposed approach: I'll add `vllm/model_executor/layers/quantization/fp8_kv_per_token.py` mirroring the existing `fp8.py` structure. Scope ~120 LOC. Test plan: extend `tests/quantization/test_fp8.py` with a per-token variant. Benchmark: compare per-token vs per-tensor on Llama-3.1 70B fp8 KV at 4K and 16K context. One open question: should the per-token scale live in the KV cache block or as a separate buffer? I see arguments for both."

**Day 1 (4 hours later)**: Maintainer reply: "Great approach. Per-token scale should live in the block — see how `vllm/attention/backends/flashinfer.py` handles V scales. Go ahead."

**Day 3**: Author opens PR. Description includes: 145 LOC changed, summary of approach, benchmark table showing 0.05 ppl improvement and 4% throughput gain at 16K, reproducer command, two open review questions.

**Day 4**: Maintainer review: 6 comments (rename one variable, add docstring, simplify a conditional, address one open question, request additional test for boundary case, suggest the perf benchmark be moved to `benchmarks/`). Author responds within 24 hours, addresses all 6.

**Day 5**: Maintainer second review: approve. CI passes.

**Day 6**: Merge.

**Day 6 (later)**: Author comments: "Thanks for the thorough review! If this is suitable for the next release notes, happy to draft a one-line summary — please mention by name if so."

**Day 7**: Maintainer adds the PR to the next release-notes draft, name included.

This is the texture. Notice what's *not* there: no force-pushes, no defensive responses, no "but I think my way is better" without reasoning. The PR landed in 6 days because the design alignment happened on day 1.

## Run it in your browser — predict your portfolio's hiring signal

<RunInBrowser
  description="Estimate the hiring signal strength of an OSS portfolio based on PR count, citation, and project distribution."
  code={`def hiring_signal(prs_per_project, cited_count, has_perf_pr):
    """
    prs_per_project: dict mapping project name to merged PR count
    cited_count: number of PRs cited by name in release notes / blog
    has_perf_pr: bool — at least one PR shipped measurable perf
    """
    total_prs = sum(prs_per_project.values())
    project_count = sum(1 for v in prs_per_project.values() if v > 0)
    
    # Base signal from raw count (sub-linear past 5)
    if total_prs <= 0: base = 0
    elif total_prs <= 3: base = 30 + total_prs * 8       # 38 - 54
    elif total_prs <= 10: base = 54 + (total_prs - 3) * 4  # 58 - 82
    else: base = 82 + min(total_prs - 10, 10) * 1.5         # 83 - 97
    
    # Citation multiplier
    citation_bonus = min(cited_count * 12, 30)
    
    # Diversity bonus (across multiple projects)
    diversity_bonus = (project_count - 1) * 5 if project_count > 1 else 0
    
    # Perf-PR bonus
    perf_bonus = 8 if has_perf_pr else 0
    
    score = base + citation_bonus + diversity_bonus + perf_bonus
    return min(score, 100)


cases = [
    ("Just starting (1 PR vLLM, no cite)",
        {'vllm': 1}, 0, False),
    ("Atlas Year-1 target (5+5 split, 1 cite, 1 perf)",
        {'vllm': 5, 'sglang': 5}, 1, True),
    ("Atlas stretch (8 vLLM, 2 SGLang, 2 FlashInfer, 2 cites, 2 perf)",
        {'vllm': 8, 'sglang': 2, 'flashinfer': 2}, 2, True),
    ("PR-count vanity (15 docs PRs, no cite, no perf)",
        {'vllm': 15}, 0, False),
    ("Quality over count (3 vLLM, 1 cite, 1 perf)",
        {'vllm': 3}, 1, True),
]

print(f"{'profile':<60}  {'score':>5}")
print("-" * 70)
for label, prs, cites, perf in cases:
    s = hiring_signal(prs, cites, perf)
    print(f"{label:<60}  {s:>4.0f}/100")

print("\\nNote: 70+ is portfolio that opens Tier-1 inference interviews.")
print("85+ is portfolio that opens elite-lab inference interviews.")
`}
/>

You'll see "quality over count" (3 PRs with 1 citation) outscores "PR-count vanity" (15 docs PRs, no citation). The signal is depth × diversity, not raw count. The Atlas Year-1 target is in the 75–80 range — comfortably enough to open Tier-1 inference interviews; the stretch goal lands in the 85–90 range, which is what elite-lab loops respond to.

## Quick check

<Quiz
  question="You've been hanging in vLLM Discord for a week and identified an issue that looks like a clean 80-LOC perf improvement. The issue was tagged 'good first issue' 3 weeks ago by @maintainer-X. You've read the relevant subsystem and have a clear plan. What's your next move?"
  options={[
    'Start coding immediately — the issue is well-scoped and you understand it; design comments are a bureaucratic step.',
    'Post a 250-word design comment on the issue with proposed approach, scope estimate, test plan, benchmark methodology, and 2 open questions for the maintainer. Wait for maintainer ack before coding.',
    'Open a draft PR with the implementation so the maintainer can see the actual code before deciding.',
    'Send a DM to the maintainer to ask if you can take the issue.',
  ]}
  answer={1}
  explanation="The design-comment-first move is what separates first PRs that land in 5–10 days from ones that sit for months. A 30-minute design comment gets a maintainer's ack (typically within 1–3 days), establishes the contract, and opens the door to fast review when the PR opens. Coding immediately wastes effort if the maintainer wanted a different approach. Draft PRs are weaker than design comments — the maintainer has to wade through code to understand intent, vs reading 250 words. DMs to maintainers are off-channel and unsearchable; future contributors with similar issues can't learn from the conversation. The discipline is in the public design comment."
/>

## Key takeaways

1. **A PR is code; a contribution is a relationship.** The disciplined moves make triage cheap so maintainers spend their attention on your code rather than figuring out whether to engage.
2. **Design comment before code.** 200–400 words on the issue, wait for maintainer ack. The 30-minute investment determines whether the PR lands in days or months.
3. **Pick by goal, not by popularity.** vLLM = highest visibility, slow review. SGLang = portfolio building. FlashInfer = kernel credibility. Triton = compiler-team gated. Mix for a balanced Year-1 portfolio.
4. **First PR teaches the codebase; the next four are 3× faster.** Aim for 5 merged in 6 months, 10 in 12, with at least one cited.
5. **Ask for the citation.** "If this is suitable for the next release notes, please mention by name — happy to draft a one-line summary." Most reviewers say yes; the contributors who don't ask don't get cited.

## Go deeper

<Resources
  items={[
    { kind: 'docs', href: 'https://docs.vllm.ai/en/latest/contributing/overview.html', title: 'vLLM Contributing Guide', author: 'vLLM contributors', note: 'The official onboarding. Read fully before your first PR.' },
    { kind: 'docs', href: 'https://docs.sglang.ai/contributing.html', title: 'SGLang Contributing Guide', author: 'sgl-project', note: 'Smaller team; the PR conventions are slightly different from vLLM. Read both.' },
    { kind: 'docs', href: 'https://triton-lang.org/main/programming-guide/chapter-1/introduction.html', title: 'Triton Contributing', author: 'triton-lang', note: 'For compiler-level work. The PR culture is more cautious — alignment first matters even more.' },
    { kind: 'blog', href: 'https://blog.vllm.ai/', title: 'vLLM Blog', author: 'vLLM contributors', note: 'Read recent release notes to see what kinds of PRs get cited and how. The pattern is replicable.' },
    { kind: 'docs', href: 'https://github.com/vllm-project/vllm/issues?q=label%3A%22good+first+issue%22', title: 'vLLM "good first issue" filter', note: 'The issue queue. Apply the three-filter discipline before picking.' },
    { kind: 'video', href: 'https://www.youtube.com/watch?v=9ih0EmcXRHE', title: 'vLLM Office Hours — Architecture & Contributing', author: 'vLLM team', note: 'Maintainer-led 60-min walkthrough. Watch before submitting your first PR.' },
    { kind: 'blog', href: 'https://github.com/sourcegraph/handbook/blob/main/content/departments/engineering/teams/code-intelligence/contribution-guide.md', title: 'Sourcegraph Code Intelligence Contribution Guide', author: 'Sourcegraph', note: 'Excellent generic OSS contribution discipline; the principles transfer to AI inference projects.' },
    { kind: 'blog', href: 'https://www.kvcache.ai/2024-09-20-Mooncake-A-KVCache-centric-Disaggregated-Architecture-for-LLM-Serving/', title: 'Mooncake — A KVCache-centric Architecture', author: 'Moonshot AI (2024)', note: 'Frontier-research blog with the same depth-and-citation pattern landing OSS PRs require. Useful as a model for your own writeups.' },
  ]}
/>

</Mode>

<Mode is="reference">

## TL;DR

- **The five rules**: (1) design comment before code, (2) scope under 200 LOC for first PR, (3) benchmarks for any perf claim, (4) follow the project's existing conventions exactly, (5) ask for citation explicitly after merge.
- **Pick the project by what you want.** vLLM = largest community, slowest review (1–3 weeks), highest visibility per PR. SGLang = smaller team, faster review (3–10 days), more contribution surface in less-tracked areas (structured output, RadixAttention). Triton = compiler-team gated, fewer PRs but higher kernel leverage. FlashInfer = the production attention library — active, tight feedback loop, where attention-kernel innovations land first.
- **The first PR teaches the codebase. The next four PRs land 3× faster.** Aim for 5 merged in 6 months as the realistic target. The portfolio matters more than any one PR.
- **Write the design comment in 200–400 words**: what you propose, scope estimate, test plan, benchmark methodology, links to relevant existing files. This is the artifact maintainers triage on.
- **The citation moment** is asking the reviewer, after merge: "if this is suitable for the next release notes, please mention by name — happy to draft a one-line summary." Most reviewers say yes to a courteous ask and forget if you don't ask.

## Why this matters

Year-1 of an AI-systems career transition has one OSS milestone: a portfolio of 5–10 merged PRs across vLLM / SGLang / Triton / FlashInfer with at least one cited by maintainers. Achieving it isn't an IQ problem or a code-skill problem; it's a process-and-discipline problem. Engineers who skip the design comment, scope past 200 LOC on a first PR, or fail to ask for citation routinely fall short of the goal despite writing perfectly good code.

This lesson is the missing process layer. After this you should be able to identify a target, post a design comment, write a PR with a benchmark table, navigate review, and ask for citation — the full sequence that converts source-reading into a portfolio.

## Mental model

```mermaid
flowchart LR
  A[Pick a project] --> B[Codebase tour<br/>1-3 days]
  B --> C[Hang in Discord/issues<br/>1 week]
  C --> D[Pick an issue]
  D --> E[Write design comment<br/>200-400 words]
  E --> F{maintainer<br/>ack?}
  F -->|yes| G[Implement + test + benchmark]
  F -->|no, refine| E
  G --> H[Open PR with full description]
  H --> I[Code review iteration<br/>1-3 rounds]
  I --> J[Merge]
  J --> K[Ask for citation]
  K --> L[Next PR is 3x faster]

Day 1 (3 hours):
  - List top-level dirs; one sentence each
  - For each major dir, find the entry point file
  - Read entry points only; note imports and called-by

Day 2 (3 hours):
  - Build dependency map (entry → role → callers)
  - Commit MAP.md to your fork's branch
  - Identify the 3 most-modified files in the last 90 days

Day 3 (2 hours):
  - For each of those 3 files, read the most recent 5 PRs that touched it
  - Note: scope, review duration, maintainer review style

## What I propose
[1-2 paragraphs. Specific files. Specific API.]

## Scope estimate
[1 paragraph. LOC by file. "If it grows past Y, I'll re-scope."]

## Test plan
[1 paragraph. Tests to extend, tests to add, edge cases.]

## Benchmark methodology (if perf-related)
[1 paragraph. Workload, metrics, reproducer command.]

## Open questions
[1-3 specific decisions for maintainer.]

Closes #123

## Summary
[2-3 sentences. Match the design comment.]

## Implementation
[3-5 bullets. Files changed and why.]

## Tests
[Bullets. Coverage detail.]

## Benchmarks (perf PRs only)
| metric | before | after |
| --- | --- | --- |
| ... | ... | ... |

Reproducer:
\`\`\`bash
python benchmarks/your_bench.py --config X
\`\`\`

## Open questions for review
[1-3 specific decisions.]

Thanks for the review! If this is suitable for the next release notes,
I'd be happy to help draft a one-line summary — please mention by name
if so.