Contributing
For people writing code for SHC itself. Audience: SHC contributors.
For operating a deployed SHC, see ../guide/. For authoring
apps on top of SHC, see ../app-development/. For
architectural internals, see ../architecture/.
Start here
Section titled “Start here”- Engineering standards: the overall bar
- CE dependency pins: corporate module routing, bumps and CI access checks
- Release lines and backports: which branch publishes where, how a fix reaches
release/v0.0, cutting a line, and what an estate’s roll MR moves - Project management: where work is tracked, how to file, and the branch/MR convention that links a merge request to its story
- Local dev servers: running console/marketplace/zkpoker/storybook and the daemon under launchd, and why starting them from an editor session does not work
Standards
Section titled “Standards”- Coding style: Go style, naming, formatting
- Commenting: when and how to comment
- Conventions: project-wide idioms
- API design: router structure, request/response types
- Error handling: coded errors (X######CCCC), POSIX exits, HTTP mapping
- Validation: input validation (validator/v10 + DecodeAndValidate)
- Testing: unit/integration/e2e expectations
- Tech stack notes: Go 1.25, cobra, chi, sqlite/rqlite, etc.
Backend
Section titled “Backend”Frontend
Section titled “Frontend”Testing
Section titled “Testing”- Overview: the test pyramid
- Writing tests: what to test and where
- Manual single-node
- Manual multi-node
- Multinode harness
Before you push: make verify
Section titled “Before you push: make verify”The GitLab pipeline builds and publishes. It does not verify. The whole correctness bar is local, and it is one command:
make verify SHC_CE_DIR=<a ce checkout>This page used to say make ci/checks and to call it “every correctness
gate”. It is not, and the cost of that sentence is measured: ci/checks is
the OUT-OF-BAND third only; it never ran gofmt, golangci-lint, shfmt, the
architectural fitness functions or a single unit test. The Makefile said so
next to ci/checks’s own definition the whole time (“make lint … and make test are the other half of the local bar”), but nothing said it here, so a
contributor who followed this page exactly could push a tree that failed both.
On 2026-08-20 origin/main was carrying five failed lint stages and nine
failing test/unit packages, none of it visible to that procedure.
make verify runs three stages and reports all three; it does not stop
at the first, because ordering one gate behind another is how a formatting
violation switches an architectural one off (measured inside lint twice):
| Stage | What it proves |
|---|---|
make lint | gofmt, golangci-lint, shfmt, jinja template validation, the architectural fitness functions, and the coded-registry / config-keys / vendored-scrub guards |
make test | test/unit + test/integration + test/docsgen + test/portaldev + test/lanelib + test/scripts + test/ce |
make ci/checks | client/check, openapi/check, docs/check, docs/lint, website/toys, ci/checks/ce-smoke, provider/build, test/rqlited-live, frontend/lint, frontend/typecheck |
Run a single gate by name when iterating (make docs/check, make lint,
make test/unit). verify refuses to start when any of its tooling (or
the ce checkout test/ce injects its corpus into) is missing, rather than
skipping a gate quietly; the failure message names everything absent at once.
A gate that did not execute is not a pass.
Some sub-gates inside test/unit DEFER by design (the pinned collector image,
the built-distro posture). Each announces itself in the run output, and verify repeats
the list on a passing run; they are named, not hidden. Run them before
cutting a tag.
The ce corpus floor is MEASURED, not written down
Section titled “The ce corpus floor is MEASURED, not written down”test/ce runs the ce module’s entire test suite, which lives in this repo
at tests/_ce/ and is injected back into a ce checkout with go test -overlay. ce ships zero in-repo *_test.go, so a lane that drops files from
that store makes go test print [no test files] for the packages it emptied
and exit 0; make test stays green over a smaller suite. The
anti-vacuity floor is what refuses that.
Do not write the corpus’s size down. It used to be a literal,
CE_TEST_FLOOR ?= <n> in the Makefile, asserted equal to the store’s exact
count. The invariant was right; the constant was not, and it failed three ways
in a single night:
- Three sessions each used a value that was correct when they learned it and stale when they used it (1430, 1431, 1434, 1435, 1440, against a tree that by then held 1441). The corpus moves several times a day; a constant cannot.
- Several lanes each computed “main’s number plus my N files”, independently arrived at the same value, and git auto-merged it with no conflict over a tree that held all of their files. Main would have gone red.
- Where it did conflict, one side said 1440 and the other 1435, and neither was right: both are counts of trees that no longer existed.
“No _ce test was silently dropped” is a measure-and-compare, not a constant.
scripts/ce-store-floor.sh now reads tests/_ce out of refs at check
time (the merge base of HEAD and origin/main for what this branch started
with, origin/main for what it is behind on) and diffs both against the
working tree. No number is stored anywhere, so there is nothing to remember,
nothing to refresh, and no line for three lanes to conflict on.
The baseline is the line the branch belongs to. A branch of dev is measured
against dev, on the remote it tracks; everything below that says
origin/main reads origin/dev there. SHC_CE_STORE_BASELINE_REF still
names a ref outright.
Run it alone with make test/ce/floor. What it does:
| Situation | Verdict |
|---|---|
| Store test present at the branch’s merge base, gone now | Refusal, naming every file |
origin/main has store tests the branch never had | Note: staleness the merge fixes, not loss |
| No merge base (grafted shallow clone, unrelated history) | Refuses on everything absent, and says it cannot tell the two apart |
origin/main unreachable and unfetchable | Refusal. A baseline it cannot read is never a pass |
Deleting a store test on purpose is legitimate, so there is one deliberate
escape hatch: raise CE_TEST_ALLOW_REMOVALS in the Makefile, in the same
commit that removes the files, to the number being removed. That puts the
intent in the diff where a reviewer sees it. Put it back to 0 once
origin/main has absorbed the removal; the check says so on every run while
the allowance is unused, and tests/unit/ci/ce_overlay_test.go fails on that
slack.
The guard test also refuses a CE_TEST_FLOOR ?= <digits> line coming back.
The indirection reads like an oversight to anyone who meets it cold, and a
literal that happens to be correct on the day it lands passes every other
check in the file.
A tier whose preconditions are absent must not report success
Section titled “A tier whose preconditions are absent must not report success”Every bats tier runs through tests/lib/tier-gate.sh, which derives the
verdict from how many tests actually executed rather than from bats’
exit status. Three states, three exit codes:
| Exit | Meaning |
|---|---|
0 | The tier RAN and passed; at least one test executed. |
1 | Failure. This includes the tier executed nothing. |
77 | The tier deliberately did not run: preconditions absent and SHC_TEST_TIER_SKIP_OK=1 said that is acceptable here. |
A missing precondition (no Proxmox host, no provisioned VMs, no formed
cluster, no docker) is a failure by default, not a skip; see
tests/lib/precondition.sh and use tier_precondition_absent for new
guards. Setting SHC_TEST_TIER_SKIP_OK=1 turns those into named skips, and
the gate then reports 77, which is non-zero so an untaught consumer fails
safe.
This exists because bats tests/proxmox/test_quota.bats on a machine
without qm used to print seven ok N … # skip Not running on Proxmox host
and exit 0. The entire proxmox tier reported SUCCESS on every CI runner and
every developer box, and three root-cause defects in it survived until it
was first run on-host. A skip claims nothing was verified; exit 0 claims
everything was. tests/unit/ci/tier_skip_semantics_test.go keeps them apart.
A skip whose SUBJECT is legitimately absent (an app with no exporter, an app with no migrations of its own, ceph on a cluster provisioned without OSD disks) is different and stays a skip; the tier around it still executed. The gate prints every skip with its reason on passing runs too, so silent coverage loss is visible in the log.
make lint (formatting, golangci-lint, the sweep-coverage check,
template validation, and the architecture fitness rules) and make test
are the other half of the local bar. They were never part of the pipeline
either.
The golangci-lint scope is one list, GOLANGCI_DIRS in the Makefile,
and every other top-level tree carrying Go files must be named in
GOLANGCI_EXEMPT_DIRS beside it with its reason.
scripts/check-lint-coverage.sh fails the target otherwise; a new
top-level package is in neither list, so it cannot slip outside the sweep
the way ./pkg/... did.
What the pipeline still gates, because it belongs to the build rather than to the codebase: the packaging checks on the binaries and debs it is about to publish, and the leak scan over the publishable corpus.
Regenerating reference docs
Section titled “Regenerating reference docs”Three reference pages are generated from the live registries so they cannot drift from the code: the error codes, the HTTP route table, and the event topics:
make docs/generate # regenerate all threemake docs/check # fail if the committed output is staleRegenerate (and commit the output) after adding, removing, or renaming an error code, an HTTP route, or an event type.
| Reference page | Source of truth | Upkeep |
|---|---|---|
docs/reference/errors.md | Per-module errors.go X####CCCC factories | generated (scripts/gen-errors-md.go) |
docs/reference/api/routes.md | Per-module router registrations | generated (scripts/gen-routes-md.go) |
docs/reference/events.md | Per-module event-type registrations | generated (scripts/gen-events-md.go) |
docs/reference/api/rpc.md | Per-package rpc_reference.go (internal_rpc.Describe) | generated (scripts/gen-rpc-md.go) |
docs/reference/cli/*.md | Per-module commands/ cobra commands | maintained by hand |
docs/reference/api/*.md (per-module notes) | Per-module router.go | maintained by hand |
docs/reference/configuration/config-keys.md | core/config/default.yaml | maintained by hand |
docs/architecture/modules/*.md (stubs) | modules/*/ (ce) + modules/*/ | maintained by hand |