This roadmap has exactly one thing that makes it different from a link list: every node is a checkable milestone, not a keyword. Contributions are welcome, but they have to hold that line. This guide is the quality gate.
Questions and half-formed ideas go to Discussions, not issues — "is §4 missing something?", "what do you think about X". Issues here are for the two templates: a resource, or a milestone.
A node is a milestone, not a topic. It must state an artifact the reader can point to.
Concretely, every node is phrased as You're done when … and ends in something checkable: a passing test suite, a workload that survives a partition, a property test over a thousand configurations, a fork your toy chain resolves, a commit function you can point at in production source. If the "done" condition is "you understand X" or "you've read about X," it is not a milestone and it does not belong here.
| ✅ A milestone | ❌ Not a milestone |
|---|---|
"You're done when make raft1 passes all 28 tests with -race, ten times." |
"Understand the Raft consensus algorithm." |
"You're done when your g-counter passes maelstrom test -w g-counter --nemesis partition." |
"Learn about CRDTs." |
| "You're done when your SWIM detector has zero false positives under 10% loss." | "Read the SWIM paper." |
This field has one dominant failure mode, and this roadmap exists to resist it: the forty-paper reading list. Papers are wonderful and several are cited here — but a paper is context for a milestone, never a milestone itself. If your suggestion is "add this paper," it must attach to a node whose artifact you build after reading it.
Resources are held to the project's standard: three excellent resources beat ten mediocre ones, and no resource appears twice. Before you propose one, it must be:
- Open — readable/runnable without a paywall, an application, or a closed cohort. (Pointing at a gated thing as a destination is fine; requiring it to do a milestone is not.)
- Live — you opened it this week and it works. Dead links and abandoned repos get removed, not added.
- Best-in-class — it is the best hands-on resource for that milestone, not merely a resource. If something already covers the milestone, argue why yours is better, or don't add it.
- Hands-on where possible — a "build/break/verify this" resource beats a "read this" resource for the same milestone.
Use the Suggest a resource issue template.
New milestones are welcome if they fill a real gap in the "working engineer → distributed systems engineer" path. Use the Suggest a milestone template and include:
- the
You're done when …line (the artifact — a command, a test, a reproducible observation), - where it fits in the section order and why,
- one candidate resource that meets the bar above — or a note that no good resource exists and the milestone is build-it-yourself.
The path map in the README is generated, never hand-drawn. Edit the SECTIONS / EDGES data at the top of scripts/render_map.py, then regenerate:
python scripts/render_map.py
CI runs python scripts/render_map.py --check and fails if assets/roadmap.svg is out of sync with the script. Commit both.
- Keyword nodes with no checkable artifact.
- A second resource that does the same job as one already present.
- Resources behind paywalls/logins, or that were already dead when submitted.
- A milestone hidden behind "you can state / you can explain" as if it were checkable. The map has exactly one openly-labeled articulation node (§10.2, career), and it says so; don't add more.
- Scope creep into the blockchain career path — that is roadmap.sh/blockchain, a different audience. Byzantine consensus gets one compact section here on purpose.
Facts only in review comments — no need for pleasantries.