Summary
Substrate has good documentation for the happy path and none for what happens when it breaks.
README.md — quickstart, both kind and GKE. Assumes everything works.CONTRIBUTING.md — process, PR sizing, root-gated tests, copyright headers.AGENTS.md — layout, build/test command reference.docs/dev/code-layout.md — where code goes.
So a contributor whose image didn't update, whose lint output is silently truncated, or whose e2e run fails on a laptop has nothing to consult. Substrate is a harder-than-average project to debug: gVisor and micro-VM sandboxes, snapshot/restore, a custom network path, a control plane deliberately outside the Kubernetes control plane, and two very different deployment targets — and the traps are mostly silent or misleading, not loud.
This issue asks for docs/dev/troubleshooting.md, organized by where you are in the dev loop.
Scope
Contributors working on Substrate. Distinct from the two other guides: the actor developer (building workloads on Substrate) and the operator (running a fleet).
A telemetry-specific troubleshooting draft already exists as a sibling issue; it should either become a section here or stay a linked companion. Recommend companion — it is deep enough to stand alone, and this guide should link to it rather than absorb it.
Summary
Substrate has good documentation for the happy path and none for what happens when it breaks.
README.md— quickstart, both kind and GKE. Assumes everything works.CONTRIBUTING.md— process, PR sizing, root-gated tests, copyright headers.AGENTS.md— layout, build/test command reference.docs/dev/code-layout.md— where code goes.So a contributor whose image didn't update, whose lint output is silently truncated, or whose e2e run fails on a laptop has nothing to consult. Substrate is a harder-than-average project to debug: gVisor and micro-VM sandboxes, snapshot/restore, a custom network path, a control plane deliberately outside the Kubernetes control plane, and two very different deployment targets — and the traps are mostly silent or misleading, not loud.
This issue asks for
docs/dev/troubleshooting.md, organized by where you are in the dev loop.Scope
Contributors working on Substrate. Distinct from the two other guides: the actor developer (building workloads on Substrate) and the operator (running a fleet).
A telemetry-specific troubleshooting draft already exists as a sibling issue; it should either become a section here or stay a linked companion. Recommend companion — it is deep enough to stand alone, and this guide should link to it rather than absorb it.