Skip to content
SHC Docs

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/.


  • 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

The GitLab pipeline builds and publishes. It does not verify. The whole correctness bar is local, and it is one command:

Terminal window
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):

StageWhat it proves
make lintgofmt, golangci-lint, shfmt, jinja template validation, the architectural fitness functions, and the coded-registry / config-keys / vendored-scrub guards
make testtest/unit + test/integration + test/docsgen + test/portaldev + test/lanelib + test/scripts + test/ce
make ci/checksclient/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:

SituationVerdict
Store test present at the branch’s merge base, gone nowRefusal, naming every file
origin/main has store tests the branch never hadNote: 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 unfetchableRefusal. 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:

ExitMeaning
0The tier RAN and passed; at least one test executed.
1Failure. This includes the tier executed nothing.
77The 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.

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:

Terminal window
make docs/generate # regenerate all three
make docs/check # fail if the committed output is stale

Regenerate (and commit the output) after adding, removing, or renaming an error code, an HTTP route, or an event type.

Reference pageSource of truthUpkeep
docs/reference/errors.mdPer-module errors.go X####CCCC factoriesgenerated (scripts/gen-errors-md.go)
docs/reference/api/routes.mdPer-module router registrationsgenerated (scripts/gen-routes-md.go)
docs/reference/events.mdPer-module event-type registrationsgenerated (scripts/gen-events-md.go)
docs/reference/api/rpc.mdPer-package rpc_reference.go (internal_rpc.Describe)generated (scripts/gen-rpc-md.go)
docs/reference/cli/*.mdPer-module commands/ cobra commandsmaintained by hand
docs/reference/api/*.md (per-module notes)Per-module router.gomaintained by hand
docs/reference/configuration/config-keys.mdcore/config/default.yamlmaintained by hand
docs/architecture/modules/*.md (stubs)modules/*/ (ce) + modules/*/maintained by hand