Capstone Project Portfolio

The guided Capstone walks you through one contribution end to end: pick a real open issue, reproduce it, trace the execution path, find the root cause, fix it, test it, land the PR, write it up. That is the minimum viable contributor cycle — one change, scaffolded by ten step-chapters that hold your hand through the workflow and grade you against the evaluation rubric.

This section is the next thing. It is a portfolio of eight larger, open-ended, self-directed engineering projects. Where the guided Capstone gives you a process with a small bug poured into it, these briefs each hand you a meaningful slice of an open Firecracker engineering problem and ask you to scope it, design it, build it, test it, and — for several — land it upstream. They are deliberately harder, deliberately less scaffolded, and deliberately aimed at the parts of the codebase a real maintainer owns: the device model, the vCPU and KVM layer, snapshotting, the rate limiter, the rust-vmm crates beneath Firecracker, CPU templates, the security boundary, and performance at density.

You do not do all eight. You do one or two, well. A single finished brief — a designed, tested, benchmarked, written-up change — is worth more on a contributor track than a dozen drive-by typo fixes. The portfolio exists so you can choose the problem that matches the muscle you want to build next, and so that when you finish it you have a portfolio-grade artifact: an upstreamable PR, a real tool, a benchmark harness with findings, or a design write-up the maintainers would recognize as serious.

Note: This curriculum will not hold your hand here least of all. Each brief points you at the right parts of the codebase with rg/gh commands, gives you the right questions, names the trade-offs, and then steps back. There is no step-by-step. If you have not yet done the guided Capstone, or you cannot run its reproduce → trace → fix → test → PR loop without the step-chapters open, go back and do it first.

How these differ from the guided Capstone

The rubric does not change. The seven dimensions — problem articulation, execution-path mastery, implementation quality, testing, review responsiveness, documentation, community interaction — translate cleanly from "bug fix" to "feature/tool/study," and the tier thresholds are identical. A finished portfolio project at 90+ is maintainer-grade work in a hard area of Firecracker. That, sustained, is the track record that gets a contributor noticed.

What this is (and what it is not)

Each brief follows a consistent shape so you can compare and plan:

1. Problem & motivation — what is missing or weak, and why it matters.
2. What you'll build — the concrete artifact.
3. Prerequisites — which levels, deep dives, and masterclasses you must have done.
4. Phased plan — Phase 0..N, from a scoped slice you can finish in a weekend to the full thing, with milestones, rg targets, and code sketches.
5. Key code areas — rg/find pointers, named by role, never by line number.
6. Design considerations & trade-offs — the decisions and what they cost.
7. How to test & validate — the pytest harness, unit tests, benchmarks.
8. Stretch goals.
9. What a strong deliverable looks like — and the upstreaming path.

The eight projects

Warning: "Difficulty" is engineering difficulty, not how mergeable the result is. Project 6 (benchmark harness) is "Medium-Hard" to build but very mergeable as tooling; Project 1 (a new device) is "Very hard" and almost certainly needs an RFC and maintainer buy-in before a line lands — the minimal-device-model philosophy sets a deliberately high bar for new attack surface. Read the "What a strong deliverable looks like" section of any brief before you start, so you scope to something that can actually land.

How to pick one

Pick along three axes, in this order.

1. The subsystem you want to own. If you came through Level 7 and the virtio masterclass and want the device model, take 1 or 8. If the snapshotting deep dive and masterclass hooked you, take 2 or 5. If you want the rust-vmm ecosystem, take 4. If security is your thing, take 7. If performance and density is, take 6 or 3.

2. The skill the rubric says is your weakest. The rubric maps a weak dimension to a kind of next contribution. Weak on testing and measurement? Projects 6 and 7 are almost entirely measurement and validation discipline. Weak on execution-path mastery? Project 1 forces you to trace a device end to end through the MMIO bus, the virtqueue, KVM, and the guest. Weak on implementation quality and scoping? Project 8's Phase 1 is a deliberately tiny, minimum-diff slice.

3. Whether you want a merge or a capability. Want a real merged PR on your profile in 4–6 weeks? Take 4 (rust-vmm), 7 (a tool the maintainers want), or the scoped Phase-1 slice of 8. Want to build a hard capability locally and possibly RFC it? Take 1, 3, or 2.

Do not pick by "which sounds most impressive." The impressive thing is a finished brief with numbers and a clean diff, whatever the topic.

The shared deliverable shape

Every brief, regardless of area, produces the same core artifacts — the same ones the guided Capstone demands, adapted for a feature/tool/study rather than a single bug fix. Keep them in a capstone-work/ directory in your fork:

• A design note (capstone-work/design.md): the problem, the constraints, the approach you chose, the approaches you rejected and why. For anything touching the wire format (snapshots), the REST API, the seccomp allowlist, or a new device, this is what you would post to the issue thread or an RFC before writing code. Firecracker maintainers expect this.
• An execution-path map (capstone-work/path.md): the existing path you traced — the device dispatch, the page-fault flow, the rate-limiter token math, the template normalization — with file references found by rg, never memorized line numbers.
• A scoped, minimum-diff implementation on a feature branch, as a sequence of small, reviewable, DCO-signed commits (git commit -s) — not one 2,000-line drop. Each commit passes tools/devtool checkstyle and builds.
• Tests at the lowest viable level: cargo test unit tests for logic, and a pytest integration test in tests/ for anything end-to-end (new functionality requires an integration test — this is a hard maintainer rule).
• Numbers, where the project is about performance (2, 3, 6, parts of 5): a reproducible benchmark, before/after, with the methodology stated and the noise characterized — not a single lucky run.
• A validation report (capstone-work/validation.md): the tools/devtool checkstyle + checkbuild --all output, the test commands, the host/kernel/CPU you ran on.
• An upstreaming decision: either a real PR (DCO-signed, with a CHANGELOG.md entry under ## [Unreleased]) or a written "here is the scoped slice I would propose, and the issue/RFC comment I would open it under."
• A write-up (500–1500 words): the engineering story, because the investigation is the durable artifact even when the code does not land.

Note: The DCO model from the guided Capstone and Licensing & DCO applies unchanged: git commit -s on every commit, no CLA, a CHANGELOG.md entry, ≥2 maintainer approvals, a maintainer merges. Project 4 (rust-vmm) is the one exception — the rust-vmm crates use their own CONTRIBUTING, CI, and review norms; that brief covers the difference.

How to present the result

A portfolio project is only as good as how you present it. Whatever you build:

• Lead with the problem and the constraint, not the code. "Restore latency is dominated by synchronous page faults under UFFD; here is the prefetch policy that cuts p99 by N% without raising memory residency" beats "I wrote a UFFD handler."
• Show the before/after. For anything measurable, a table with the host/kernel/CPU stated. For a tool, a sample of its output on a real run.
• Show the diff is clean. A reviewer should be able to read your commits as a story. Squash the false starts.
• State what you did not do, and why. Scope discipline is a maintainer signal. "I deliberately did not change the on-wire snapshot format because that needs a versioning RFC" is a strong sentence.
• Make it reproducible. Someone should be able to clone your fork, run one command, and see what you saw. The harness is the deliverable for Projects 6 and 7.

Before you start any brief

1. You finished the guided Capstone, or you can run its workflow without the step-chapters open.

2. You can build and test Firecracker from source with tools/devtool (Levels 1 and 5): tools/devtool build and tools/devtool test. Confirm:

   ls -l /dev/kvm                 # the one hard requirement
   tools/devtool build --release  # produces build/cargo_target/.../release/firecracker
   

3. You read the brief's "What a strong deliverable looks like" section first, so you scope Phase 1 to something that can actually land or be RFC'd, and you check the area is still live before you start (every brief gives you the rg/gh anti-staleness commands).

Then pick one. Project 4 is the natural start if you want a real upstream merge with the cleanest process; Project 6 or Project 7 if you want a high-mergeability tool; Project 1 if you want the hardest, most complete systems build in the curriculum.

Next: pick a brief. If you are undecided, skim Project 4 (rust-vmm upstream) for the cleanest path to a merge, then Project 1 (a new virtio device) for the most ambitious build.