Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Lab 19-01 — Find and Scope a Real Upstream PR [CPU-OK]

Nineteen phases built the knowledge; this lab spends it. You will triage real open vLLM issues, run the checks that separate a contributable issue from a trap, and produce the lab's artifact: a one-page implementation plan for one issue — written to the standard where a maintainer reading it would say "yes, do that." This is a process lab: no starter.py, no tests. The deliverable is the plan, and the grader is eventually the vLLM review queue itself.

Contents

Why this lab exists

The distance between "understands vLLM" and "has a merged vLLM PR" is not knowledge — it's selection and scoping, and most first-time contributors fail there: they pick an issue that's secretly hard, already claimed, or quietly obsolete, burn two weekends, and bounce off. The defense is treating issue triage as an engineering activity with checks, which is also — not coincidentally — what maintainers themselves do all day. Doing this lab honestly once gives you the habit; the habit gives you the merged PR; the merged PR (per CAREER.md) is the portfolio line that compounds.

Step 1 — Harvest candidates

gh issue list -R vllm-project/vllm --label "good first issue" --state open --limit 30
gh issue list -R vllm-project/vllm --label bug --state open --search "sort:created-desc" --limit 30

Pick three candidates with different shapes if you can: a model-support gap (Phase 14's mapping-row class), a parser/frontend bug (Phase 16's territory), and a docs/test gap (don't sneer — test PRs teach the review process at minimum stakes). For each, skim the issue thread fully: maintainer comments often contain the scoping ("this needs X first", "blocked on Y") that the title hides.

Step 2 — The disqualification gauntlet

Run every candidate through these checks — in this order, cheapest first:

  1. Already claimed/fixed? gh pr list -R vllm-project/vllm --search "<keywords>" plus a search of closed PRs and linked PRs in the issue. The most common first-timer waste is duplicating an in-flight fix. (The repo's AGENTS.md encodes exactly these checks for AI-assisted contributors — read it; the checklist applies to humans identically.)
  2. Still reproducible at HEAD? Issues rot; vLLM merges dozens of PRs daily. A bug filed three weeks ago may be gone. Reproduce (or for model-support, confirm the model still errors) before writing a line.
  3. Is the cause within your current map? Trace it to a file. If the file is one whose machinery you've built in this course (scheduler, block pool, parsers, loaders, sampler, platform code) — green. If it's deep in a CUDA kernel and you skipped the GPU labs — pick another, or budget honestly.
  4. Is the fix small but the test meaningful? The ideal first PR is a ≤100-line diff with a regression test that pins the behavior forever — the shape every lab in this course drilled. Issues whose fix is one line but whose test is impossible, or vice versa, score worse than they look.
  5. Will anyone review it? Check the subsystem's recent merge velocity (gh pr list --search "path:vllm/<area>" --state merged --limit 10). A perfect PR into an unowned corner can sit for months; that's demoralizing precisely when momentum matters most.

Expect to disqualify two of three. That's the gauntlet working, not failing.

Step 3 — Scope the survivor

For the survivor, do the course's move: find the load-bearing lines. Identify the function(s) to change, the invariants they maintain (you can usually name them now — I1–I4, the budget cap, chunking invariance, the contract widths), the test file where the regression test belongs, and the blast radius (who calls this? does TP/quant/LoRA/spec-decode interact? — the feature-composition questions Phases 10–12 trained).

The one-page plan (the artifact)

Issue: #NNNNN — <title>                       Reproduced at: <commit>
Cause (file:line): ...                        (one paragraph, mechanism not symptom)
Fix sketch: ...                               (what changes, why it preserves the invariants)
Test plan: ...                                (the regression test: file, fixture, the assert)
Blast radius: ...                             (interactions checked: TP / quant / LoRA / spec / none)
Out of scope: ...                             (the adjacent improvements you are NOT doing — scoping
                                               discipline is mostly this line)
Open questions for maintainers: ...           (≤2, specific — these go in the PR description)

One page. If it doesn't fit, the scope is wrong — shrink the issue, not the font.

Hitchhiker's notes

  • Comment on the issue before coding ("I'd like to take this; plan: ") — it claims the work, invites early correction, and costs nothing. Maintainers redirect cheap plans gladly and expensive PRs reluctantly.
  • Read docs/contributing/ and run the pre-commit hooks before the first commit — format/lint failures are the #1 cause of first-PR friction, and they're entirely avoidable mechanically.
  • The DCO sign-off (git commit -s) is required and forgotten by almost every first contributor. Set git config alias.cs "commit -s" now.
  • Your course artifacts are your credibility: a PR description that says "this preserves the free-queue invariant (blocks in queue ⟺ ref_cnt==0)" or "verified chunking-invariance with a randomized-slicing test" reads as a peer, not a tourist. Use the vocabulary; you've earned it.

Going further

  • Do it: implement the plan, open the PR, survive review. Review is the lab's second half — expect a round or two; respond to every comment (fix or argue, never silence). The merge is Phase 19's true exit criterion.
  • Then do the maintainer's side once: pick someone else's open first-PR and review it against your gauntlet — kindly, concretely. Both seats teach.
  • Keep the plan template. Every nontrivial change you ever make — upstream or at work — deserves the one-pager; teams that institutionalize it ship faster and argue less.

References