From a0a66c10a7705380b23efd03cf168ac0e6adda74 Mon Sep 17 00:00:00 2001 From: Compot Developer Date: Fri, 16 Oct 2026 23:50:26 +0000 Subject: [PATCH 1/4] Add CLAUDE.md: local checks in pinned Docker images Records the commands for the CI lint job's checks (shellcheck on the scripts, native build, shellcheck on the init script the binary writes) in pinned images with --pull never, so agent sessions stop using the moving koalaman/shellcheck:stable tag or building on the host. Closes 27 --- CLAUDE.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..141491e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,43 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Local checks run in Docker + +Nothing is installed on the host: no compiler, mbedTLS or shellcheck. Every image tag below is +pinned, and each one runs with `--pull never`, so a check never pulls a different version than +the last run. + +The same checks as the CI `lint` job: + +```sh +# shell scripts +docker run --rm --pull never -v "$PWD:/mnt" -w /mnt koalaman/shellcheck:v0.10.0 \ + -S warning install.sh uninstall.sh ci/build.sh ci/assemble.sh tests/run.sh tests/suite.sh + +# native build (mbedTLS 2.28 from Debian bookworm), then lint the init script the binary writes +docker run --rm --pull never -u "$(id -u):$(id -g)" -v "$PWD:/src:ro" compot/cross:2026.10 \ + sh -c 'cp -r /src/src /tmp/s && make -s -C /tmp/s EXTRA_CFLAGS=-Werror >&2 && /tmp/s/cerberus init-script -' \ + > /tmp/cerberus.init +docker run --rm -i --pull never koalaman/shellcheck:v0.10.0 -S warning -e SC2155 -s sh - < /tmp/cerberus.init +``` + +Use `koalaman/shellcheck:v0.10.0`, not `:stable`: the `stable` tag moves between releases. +`make -s` sends its size line to stderr (`>&2`); without that it lands in the script and the +lint fails with SC2275. + +Tests and release binaries already run in containers through the repository's own scripts: + +```sh +tests/run.sh # alpine:3.20, musl + mbedTLS 3.x +CERBERUS_TEST_IMAGE=debian:bookworm-slim tests/run.sh # glibc + mbedTLS 2.28 +ci/build.sh arm # static musl binary; all four without arguments +``` + +## Rules + +- Never build on the host. `make -C src` outside a container leaves a host-built `src/cerberus` + behind. +- Local builds are for development only. Releases come from CI on a `v*` tag. +- PRs are prepared here, then handed to @keyldev for review. They are not merged from here, + and nothing is pushed to `master`. From f03a6da6be7273cd380eec2e76a53d819d10871c Mon Sep 17 00:00:00 2001 From: Compot Developer Date: Sat, 17 Oct 2026 00:13:57 +0000 Subject: [PATCH 2/4] CLAUDE.md: compot images are not published; plain Debian equivalent of the native build Same layout as vtesse's CLAUDE.md: "Local builds and checks", then Rules. The equivalent was checked: debian:bookworm-slim with gcc, make, libc6-dev and libmbedtls-dev builds src/ with -Werror and writes the init script. --- CLAUDE.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 141491e..91d1413 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,13 +2,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -## Local checks run in Docker +## Local builds and checks -Nothing is installed on the host: no compiler, mbedTLS or shellcheck. Every image tag below is -pinned, and each one runs with `--pull never`, so a check never pulls a different version than -the last run. +Everything runs in Docker. Nothing is installed on the host: no compiler, mbedTLS or +shellcheck. Every image tag below is pinned. The direct `docker run` commands pass +`--pull never`, so a check never pulls a different version than the last run. -The same checks as the CI `lint` job: +`compot/*` images are not published. They are built on a maintainer's development machine +from Dockerfiles kept outside this repository. Elsewhere, use the equivalent command marked +*without compot*; it gives the same result. + +The CI `lint` job checks: ```sh # shell scripts @@ -20,6 +24,11 @@ docker run --rm --pull never -u "$(id -u):$(id -g)" -v "$PWD:/src:ro" compot/cro sh -c 'cp -r /src/src /tmp/s && make -s -C /tmp/s EXTRA_CFLAGS=-Werror >&2 && /tmp/s/cerberus init-script -' \ > /tmp/cerberus.init docker run --rm -i --pull never koalaman/shellcheck:v0.10.0 -S warning -e SC2155 -s sh - < /tmp/cerberus.init + +# the same native build without compot: plain Debian bookworm, packages installed per run +docker run --rm -v "$PWD:/src:ro" debian:bookworm-slim sh -c \ + 'apt-get update -qq && apt-get install -y -qq --no-install-recommends gcc make libc6-dev libmbedtls-dev >/dev/null && + cp -r /src/src /tmp/s && make -s -C /tmp/s EXTRA_CFLAGS=-Werror >&2 && /tmp/s/cerberus init-script -' > /tmp/cerberus.init ``` Use `koalaman/shellcheck:v0.10.0`, not `:stable`: the `stable` tag moves between releases. From fd96eaeadecb7f8018941c3291870233366197f0 Mon Sep 17 00:00:00 2001 From: Compot Developer Date: Sat, 17 Oct 2026 00:31:29 +0000 Subject: [PATCH 3/4] CLAUDE.md: name the Alpine test image without its version (tests/run.sh holds it) --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 91d1413..20b9186 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -38,7 +38,7 @@ lint fails with SC2275. Tests and release binaries already run in containers through the repository's own scripts: ```sh -tests/run.sh # alpine:3.20, musl + mbedTLS 3.x +tests/run.sh # Alpine (default image in tests/run.sh), musl + mbedTLS 3.x CERBERUS_TEST_IMAGE=debian:bookworm-slim tests/run.sh # glibc + mbedTLS 2.28 ci/build.sh arm # static musl binary; all four without arguments ``` From 77dec90a83010c1e146714162076dc107c25fdaa Mon Sep 17 00:00:00 2001 From: wudgexyz Date: Sat, 17 Oct 2026 23:49:34 +0300 Subject: [PATCH 4/4] CLAUDE.md: plain Debian build only, no merge rule, one-time pulls The native build used compot/cross, which is not published, so the first command failed everywhere but one machine; the debian:bookworm-slim command is now the only one. The rule against merging from a session applied to every session in the repository, the maintainer's included, and is gone. "Releases come from CI on a v* tag" would go stale with #32; it now says only that release binaries come from CI. --pull never needs the images once, so the first block pulls them. The version-bump rule from #33 is named, with check-version.sh for a local run. --- CLAUDE.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 20b9186..30496ca 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,12 +5,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Local builds and checks Everything runs in Docker. Nothing is installed on the host: no compiler, mbedTLS or -shellcheck. Every image tag below is pinned. The direct `docker run` commands pass -`--pull never`, so a check never pulls a different version than the last run. +shellcheck. shellcheck is pinned to a release and the build image to a Debian release +(bookworm, mbedTLS 2.28). The `docker run` commands pass `--pull never`, so a check never +pulls a different version than the last run. On a fresh machine, pull the images once: -`compot/*` images are not published. They are built on a maintainer's development machine -from Dockerfiles kept outside this repository. Elsewhere, use the equivalent command marked -*without compot*; it gives the same result. +```sh +docker pull koalaman/shellcheck:v0.10.0 +docker pull debian:bookworm-slim +``` The CI `lint` job checks: @@ -20,21 +22,20 @@ docker run --rm --pull never -v "$PWD:/mnt" -w /mnt koalaman/shellcheck:v0.10.0 -S warning install.sh uninstall.sh ci/build.sh ci/assemble.sh tests/run.sh tests/suite.sh # native build (mbedTLS 2.28 from Debian bookworm), then lint the init script the binary writes -docker run --rm --pull never -u "$(id -u):$(id -g)" -v "$PWD:/src:ro" compot/cross:2026.10 \ - sh -c 'cp -r /src/src /tmp/s && make -s -C /tmp/s EXTRA_CFLAGS=-Werror >&2 && /tmp/s/cerberus init-script -' \ - > /tmp/cerberus.init -docker run --rm -i --pull never koalaman/shellcheck:v0.10.0 -S warning -e SC2155 -s sh - < /tmp/cerberus.init - -# the same native build without compot: plain Debian bookworm, packages installed per run -docker run --rm -v "$PWD:/src:ro" debian:bookworm-slim sh -c \ +docker run --rm --pull never -v "$PWD:/src:ro" debian:bookworm-slim sh -c \ 'apt-get update -qq && apt-get install -y -qq --no-install-recommends gcc make libc6-dev libmbedtls-dev >/dev/null && cp -r /src/src /tmp/s && make -s -C /tmp/s EXTRA_CFLAGS=-Werror >&2 && /tmp/s/cerberus init-script -' > /tmp/cerberus.init +docker run --rm -i --pull never koalaman/shellcheck:v0.10.0 -S warning -e SC2155 -s sh - < /tmp/cerberus.init ``` Use `koalaman/shellcheck:v0.10.0`, not `:stable`: the `stable` tag moves between releases. `make -s` sends its size line to stderr (`>&2`); without that it lands in the script and the lint fails with SC2275. +A pull request that changes `src/`, the installers, the `Makefile` or `ci/` also needs a new +`CERBERUS_VERSION` in `src/cerberus.c` and its section in `CHANGELOG.md`; CI checks that with +`.github/check-version.sh`, which runs the same locally against `origin/master`. + Tests and release binaries already run in containers through the repository's own scripts: ```sh @@ -47,6 +48,4 @@ ci/build.sh arm # static musl binary; al - Never build on the host. `make -C src` outside a container leaves a host-built `src/cerberus` behind. -- Local builds are for development only. Releases come from CI on a `v*` tag. -- PRs are prepared here, then handed to @keyldev for review. They are not merged from here, - and nothing is pushed to `master`. +- Local builds are for development only. Release binaries come from CI, never from a local build.