Explanation¶
Explanation pages are understanding-oriented — the why, not the how. Each one distils one or more decision records into a readable account of a design choice and the reasoning behind it. If you want the how, see How-To Guides or Reference; the exhaustive, dated source material is the decision log.
Pages¶
- Spec-first development — why every change starts as a dated spec, and what that buys.
- The token-input convention: why every
credential is an input, defaulting to
$CI_JOB_TOKENwhere the job token can do the work and to a purpose-named variable where it cannot. - OpenTofu state and caching — OIDC plan/apply, the GitLab-managed HTTP backend, provider and module caching.
- The dev-tools image: why the Go, Rust and Svelte components run on a baked toolchain image instead of installing tools at job time, told through the image that has since been split into one per track.
- Change-detection — the
rules:changesmechanism, its reliability constraints, and why it's default-on everywhere except security. - Security: always-on — why every security scanner is exempt from change-detection and runs on every MR regardless.
- Release automation — the shape shared by
goreleaser,release-plz,tofu-module-publish, andreleaser-pleaser, and where they differ. - Renovate automation — the
renovate-selfcomponent and the bundled preset that keeps every consumer's component pins current. - A skip is not a pass — why a suite gated behind an env var must fail, not skip, when the gate is on and its dependency is missing, and why that lives in the test helper.
- Static sites —
zensical-pagesandhugo-pages, and whyhugo-pagesis the one component that deploys on a schedule. - The Svelte frontend track — embedding a
Svelte UI in a Go binary, and the
go:generate-vs-svelte-builddecision.
The exhaustive, dated source material every page above draws from is the decision log.