From 52ea715d606991b7150d99c0f03104776359ad2c Mon Sep 17 00:00:00 2001 From: atlas Date: Fri, 19 Jun 2026 12:16:46 +0200 Subject: [PATCH] docs: document the build + local-check workflow in conventions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Devshell-only builds (no global toolchain), nix fmt as the authoritative formatter, and the full-flake-check gates the devshell misses — notably the hivectl-docs regen after any hivectl verb/flag change. Pulled out of the hive-wide knowledge repo, which keeps only the portable kernel. --- docs/conventions.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/conventions.md b/docs/conventions.md index 86112af0..2894bdba 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -406,6 +406,50 @@ Stage and commit when work *looks* ready, then run validation follow-up commit rather than an amend. The commit history is the work log; rewriting it loses signal. +## Building & local checks + +Build through the **flake devshell**, not a bare toolchain — agent +containers ship no global rust. `nix develop -c ` runs one +command inside the project-pinned env (cargo/clippy/rustfmt plus the +C compiler + `libsqlite3`/`ring` link deps); outside it a bare +`cargo build` fails with `failed to find tool "cc"` / `cannot find +-lsqlite3`. One command per invocation — agents run each task as a +fresh non-interactive process, so there's no persistent shell to +reuse. + +```sh +nix develop -c cargo clippy --all-targets -- -D warnings +nix develop -c cargo test +nix fmt # treefmt — authoritative, NOT bare cargo fmt +``` + +`nix fmt` (treefmt) is the formatter CI gates on; bare `cargo fmt` +misses the non-rust files treefmt also covers, so always run `nix +fmt` before pushing. + +**The devshell checks are not the full `nix flake check`.** Clippy / +fmt / `cargo test` cover most gates, but `nix flake check` runs extra +check derivations they don't: + +- **`hivectl-docs`** regenerates `docs/tools/hivectl-cli.md` from + hivectl's clap tree and **fails if the committed copy is stale**. + So **after any change to a hivectl verb or flag, regenerate it**: + ```sh + nix develop -c cargo run --bin hivectl -- markdown-docs > docs/tools/hivectl-cli.md + ``` + clippy / fmt / `cargo test` all pass *without* this — only the + flake check catches the drift, and `ci-log` often can't show you + why (it 500s on a fast failure), so you're left guessing "builder + flake" when it's a stale doc. +- there's also a flake `cargo-test` check and NixOS module + evaluation in the set. + +When local clippy/fmt/test pass but CI's `nix flake check` fails, +**don't assume a transient builder problem** — reproduce the real +gate locally: `nix flake check` (shares the build farm, use +sparingly) or build just the suspect check, e.g. `nix build +.#checks.x86_64-linux.hivectl-docs`. + ## Best-effort oneshot services The harness ships a family of one-shot systemd services that