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

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

• API
• Migrations

• Components
• CSS
• Responsive
• Accessibility

• Overview — the test pyramid
• Writing tests — what to test and where
• Manual single-node
• Manual multi-node
• Multinode harness
• Proxmox test harness

The GitLab pipeline builds and publishes. It does not verify. Every correctness gate that used to run there now runs here, in one command:

make ci/checks

That runs, in order:

Run a single gate by name when iterating (make docs/check). The target refuses to start when any of its tooling is missing rather than skipping a gate quietly; the failure message names what to install.

make lint (formatting, golangci-lint, 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.

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:

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.