Community Interaction

Every interaction you have on the Firecracker project is part of a permanent, public record that a maintainer can read in five minutes before deciding how much of their time you are worth. That is not cynical; it is how a small AWS team triages a firehose of issues and PRs from strangers. A well-formed issue, a respectful comment that shows you read the code, a question that proves you did your homework — these mark you as someone worth engaging. A vague "doesn't work" issue, a "+1" on a year-old thread, or a demanding tone marks you as noise to route around.

This chapter is the etiquette of the Firecracker community: how to file and claim issues, how to ask questions that get answered, which channel is which — and the one rule that, if you get it wrong, does real damage: security issues are reported privately, never in public.

Note: Firecracker is single-vendor governed — a dedicated AWS team, no foundation, no steering committee, no community Slack workspace of the kind larger projects run. The channels are few and deliberate: GitHub issues and PRs for everything public, the firecracker-maintainers@amazon.com mailing list for maintainer-directed questions, and a private path to AWS Security for vulnerabilities. Read CONTRIBUTING.md and SECURITY.md first; everything below elaborates them.

The Channels, and What Each Is For

cd ~/fc-src
sed -n '1,80p' CONTRIBUTING.md     # contribution rules, issue/PR expectations
sed -n '1,60p' SECURITY.md          # the private reporting path — read before you ever file

The default for everything non-sensitive is public, in the open, on GitHub. Working in public is a feature: it builds the track record this curriculum is ultimately about (maintainership). The exception is security, and it is absolute.

Reporting Security Issues: Privately, Always

This is the single most important rule in this chapter, so it comes first.

Warning: If you find — or even suspect — a vulnerability in Firecracker (a guest-to-host escape, a way past seccomp or the jailer, a denial-of-service against the host, an attack-surface hole in a device, a memory-safety bug reachable from the guest), do not open a public issue, do not open a public PR, do not mention it in a public comment, and do not post a proof-of-concept. Report it privately through the process in SECURITY.md, which routes to AWS Security.

The reason is the threat model. Firecracker is the isolation boundary under AWS Lambda and Fargate — thousands of untrusting tenants per host. A publicly disclosed, unpatched escape is an active danger to real multi-tenant production systems before a fix and a coordinated release exist. Responsible disclosure — private report, coordinated fix, CVE, then public detail — is how the project protects its users. (CVE-2026-5747, the virtio-PCI transport vulnerability fixed in 1.14.4/1.15.1, followed exactly this path; verify the specifics on the advisories.)

The instinct to build: "could this be a security issue?" is a question you ask before you type anything in a public box. If the answer is yes or maybe, the public box is the wrong box. When in doubt, treat it as security and report privately; over-caution here costs nothing, under-caution can be catastrophic.

# The authoritative process — read it now, not when you're mid-discovery.
rg -n -i "security|vulnerabilit|disclos|report" SECURITY.md

Filing a Good Issue

A maintainer triaging issues is asking one question: "can I act on this without a round-trip of follow-up questions?" Make the answer yes. A maintainer-actionable Firecracker bug report has:

• Version — the Firecracker version (./firecracker --version) and how you built it (tools/devtool build, release/debug, musl/gnu), plus host arch and kernel.
• A minimal reproduction — the smallest sequence of API calls (the curl --unix-socket PUTs and the InstanceStart) or config file that triggers it. Strip everything not needed to reproduce.
• Expected vs actual — what you expected and what happened, with exact output, error strings, and relevant logs (--log-path).
• Guest details if relevant — the kernel and rootfs you used (CI artifacts, or your own).

# Capture the facts a good report needs:
./firecracker --version
uname -srm
# A minimal repro is a short script of the canonical boot sequence (see Lab 1.3),
# trimmed to exactly the calls that trigger the bug.

A bug report that boots a microVM with a five-line curl script and shows the failure is reproducible in two minutes by a maintainer. A report that says "snapshots are broken" with no version, config, or repro is unactionable and will be labeled and left. The asymmetry is enormous: ten minutes of your effort writing a clean repro saves hours of round-trips and gets your issue fixed; sloppiness gets it ignored.

Tip: Search before you file. gh issue list --repo firecracker-microvm/firecracker --search "your symptom" and --state all to catch closed/duplicate issues. A duplicate filed without searching reads as "I didn't do my homework."

Claiming and Working an Issue

Firecracker labels beginner-friendly work good first issue. The etiquette for taking one:

gh issue list --repo firecracker-microvm/firecracker --label "good first issue" --state open
gh issue view <NNNN> --repo firecracker-microvm/firecracker --comments

• Comment to claim, then start. A short "I'd like to work on this — planning to approach it by X" both reserves it and surfaces your approach so a maintainer can redirect you before you write the wrong fix.
• Don't hoard. Claim one, work it, ship it. Claiming five issues and delivering none is worse than claiming none — it blocks others and signals unreliability.
• If you go quiet, say so. If life intervenes, comment that you're stepping back so someone else can take it. Abandoned-without-a-word claims are how issues rot.
• Confirm scope before big work. For anything beyond a good first issue, propose the approach in the issue and get a maintainer's nod before investing days. An unrequested 800-line PR that solves the problem the "wrong" way is a hard sell, no matter how good the code.

Level 2 Lab 3 walks a full claim-to-PR cycle on a real good-first-issue; this chapter is the etiquette that surrounds it.

Asking Good Questions

The maintainers will engage a question that shows you did the work and ignore one that asks them to do it for you. The difference is concrete:

The pattern in the right column: you state what you already found, where, and what you concluded, and you ask a specific, answerable question. That respects the maintainer's time, proves you can be trusted with a real answer, and — not incidentally — often gets you the answer faster because you've done the maintainer's first three diagnostic steps already.

Before asking, exhaust the self-serve sources from Design via GitHub: docs/, the swagger, the relevant deep dive, the FAQ, and a search of existing issues. "I read X, Y, and Z and I'm still stuck on this specific point" is a question a maintainer is glad to answer.

Tone, Patience, and What Gets Engaged

The Firecracker maintainers are a small team supporting production infrastructure for the entire AWS serverless platform and a public open-source project. Review bandwidth is finite and precious. Internalize three things:

1. Patience. A PR or issue may sit for days or weeks before a maintainer reaches it. That is not a snub; it is a queue. Bumping a thread daily does not move you up it — it adds noise. A single, polite "gentle ping" after a reasonable interval is fine; a stream of "any update?" is not.
2. Tone. Entitlement ("why hasn't anyone looked at my PR"), arguing past a "no," or treating a maintainer's "no" as a negotiation to be won by persistence all damage you. A "no" backed by the threat model or the minimal-device-model philosophy is a design position, not an opening bid. Disagree with evidence, concede with grace (see responding to feedback).
3. Respect the scope boundary. Firecracker says "no" to a lot, by design. "QEMU has it" / "Cloud Hypervisor has it" is not an argument — Firecracker's whole thesis is not being those. A proposal framed as "here is my isolation-preserving need and I've read why the device model is minimal" gets a real conversation; "add this feature" gets a pointer to the FAQ.

Validation: Prove You Understand This

1. State the rule for security issues in one sentence, and name the file that defines the process. Explain why the threat model makes public disclosure dangerous.
2. Write a complete, minimal bug report for a hypothetical boot failure: version, repro (the actual curl/config), expected vs actual, logs. Keep it to what a maintainer needs.
3. Rewrite a low-effort question ("how does X work?") into a high-effort one that cites a file and the doc you already read.
4. Find one open good first issue, and write the comment you'd post to claim it — including the approach you'd take.
5. Name the four channels and exactly what each is and is not for, including firecracker-maintainers@amazon.com.
6. Describe how you'd respond to a maintainer "no" rooted in the minimal-device-model philosophy without arguing or going silent.

You have absorbed this chapter when your reflex before posting anything is: "is this a security issue? have I done my homework? is this the right channel? would I want to receive this?" The next chapter — PR Quality and Preparation — is what you produce once you've talked to the community and you're ready to ship.