From a9586d3034a380e471f7305ac39dd351866bf60f Mon Sep 17 00:00:00 2001 From: BattermanZ Date: Sun, 15 Nov 2026 09:05:19 +0100 Subject: [PATCH] docs: release checklist asks for the newest base images A release ships whatever base images the Dockerfile names, and the pinned distroless digest and Rust version never move by themselves. A new box on the version-bump pull request has the agent bring them up to date, and the hook contract now asks images to fetch every base image fresh. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013rPDLhkh1Xdj28Bu6KMVGV --- docs/adr/0047-a-release-is-cut-by-two-commands.md | 2 +- docs/releasing.md | 6 ++++++ ui/tools/release-common.mjs | 1 + ui/tools/release-common.test.mjs | 4 ++-- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/adr/0047-a-release-is-cut-by-two-commands.md b/docs/adr/0047-a-release-is-cut-by-two-commands.md index 51c37393..904cefbd 100644 --- a/docs/adr/0047-a-release-is-cut-by-two-commands.md +++ b/docs/adr/0047-a-release-is-cut-by-two-commands.md @@ -28,7 +28,7 @@ - **No What's new page, no docs-freshness check, no roadmap.** Kamosu has none of the three, so their checks and refusals are left out. - **The changelog keeps an empty `## Unreleased`.** `release-prepare` dates the section and leaves a new, empty one above it, because a ticket adds its line under that heading in the same commit as its change. - **Two gates in place of one.** Kamosu has no `just check-full`. The bump must pass `just check` and then `just test`. -- **Five checklist items of Kamosu's own**: the glossary, the previous release's library, `just audit`, `THIRD_PARTY_NOTICES.md` and the Docker Hub overview. The last came with [#235](https://github.com/BatterWorks/Kamosu/issues/235), when the hook took on publishing that page. +- **Checklist items of Kamosu's own**: the glossary, the previous release's library, `just audit`, `THIRD_PARTY_NOTICES.md`, the Docker Hub overview, the Demo's Sample Library, the agent image's Alpine fixes, and the newest base images for Kamosu's image. The Docker Hub overview came with [#235](https://github.com/BatterWorks/Kamosu/issues/235), when the hook took on publishing that page. The base images came after v2.10.0 of Hatchdoor shipped on an old runtime digest: a pinned base never moves by itself. ## Considered options diff --git a/docs/releasing.md b/docs/releasing.md index ff8c402b..97075bd5 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -138,6 +138,11 @@ These are the checks only a reader can make. `release-prepare` puts them on the - **A Demo's Sample Library builds on this release: `just sample-library` prints what it holds.** It plays the story in `sample-library/story.json` through this release's Operations, as a Demo does when it starts, into `.dev/sample-library`. A step an Operation now refuses fails it, naming the step. It then pours the library into a Demo of its own under `.dev/sample-library/as-a-demo`, given a public address the way a Demo started with `KAMOSU_DEMO_PUBLIC_ADDRESS` stores one, and fails if a shared recipe there has no link to copy (#468). Fix the story on the bump branch, since a Demo that cannot build its library does not start. `sample-library/README.md` says how the story is written. - **`just audit` is clean, or each advisory it reports is recorded in `deny.toml` with its reasoning.** Read what it reports instead of obeying it. A remedy `npm audit` suggests is often a downgrade. - **The agent image has Alpine's security fixes: if the Alpine release it is built on has published fixes for a package in it since it was last built, the bump branch edits the rebuild line in `agent-image/Dockerfile`.** The agent image is built again only when `agent-image/` changes, so without this an unchanged image keeps old copies of ffmpeg, python3 and curl in the one container that fetches what strangers send. The rebuild line names the date of the fixes it was built for. Read [Alpine's security tracker](https://security.alpinelinux.org/) for the release in the Dockerfile's `FROM` lines, for any fix to a package the image installs, or to the base image, since that date. If there is one, write today's date into the line on the bump branch, commit, and run `release-prepare` again. That change to `agent-image/` is what makes the hook build the image again. +- **Kamosu's image is built on the newest base images: the distroless runtime digest, Rust in the Dockerfile and `rust-toolchain.toml`, and the Node major.** A release ships whatever base images the Dockerfile names, and a pinned one never moves by itself, so the image keeps old copies of OpenSSL and zlib from its runtime base until someone moves the pin. On the bump branch: + - The runtime, `gcr.io/distroless/cc-debian13:nonroot`, is pinned by digest. Set the digest to the one `docker buildx imagetools inspect gcr.io/distroless/cc-debian13:nonroot` prints on its `Digest:` line. + - Rust moves in both places together: the `rust:-slim` builder tag in the Dockerfile and `channel` in `rust-toolchain.toml`. Set both to the newest stable Rust, the tag to its `X.Y` and the channel to its newest `X.Y.Z`. A new Rust can bring new clippy warnings; `just check` finds them on the next `release-prepare`, and they are fixed on the bump branch. + - The UI builder, `node:-slim`, is a moving tag, so a build fetches its newest image. Check that its major is still supported upstream, and move it when a newer LTS major is out. + - When nothing changed, tick the box. Otherwise commit, add a line under the dated `## v` section saying the image is built on updated base images, and run `release-prepare` again. - **`THIRD_PARTY_NOTICES.md` matches the dependencies that ship.** Everything bundled in the repository, in the agent image, or downloaded at runtime by an Operator is named there with its licence, and nothing removed since the previous release is still listed. Compare it against `git diff v..origin/dev -- assets/ Cargo.toml ui/package.json src/meaning.rs agent-image/`. - **The release title and notes are drafted.** Step 3. @@ -182,6 +187,7 @@ The machines that build the images and the credentials that push them are not de `images` must: +- Fetch every base image a Dockerfile names from its registry on each build, never reusing a copy the build machine already holds, so a moving tag such as `node:24-slim` gives its newest image. - Build from the tagged commit, never from a working tree, and pass every build `--build-arg VERSION=` and `--build-arg GIT_SHA=`. The Dockerfile writes them to the `org.opencontainers.image.version` and `org.opencontainers.image.revision` labels, which are empty without them. - Push two tags to `battermanz/kamosu` on Docker Hub, each for amd64 and arm64: `` and `latest`, from one Docker build. Docker and Podman both run that image. Releases up to 0.5.0 also pushed a Podman-built pair, `podman-` and `podman-latest`, which #483 dropped: Podman runs the Docker-built image as it is, so the second build cost a release time and gave readers two pairs to choose between for nothing. Those tags stay on Docker Hub where they are, and `images` never reads or moves them. - Skip a tag that already points at the image it would push, and refuse if a different image sits under the version. A published version is never overwritten. diff --git a/ui/tools/release-common.mjs b/ui/tools/release-common.mjs index c8f505df..a18964fa 100644 --- a/ui/tools/release-common.mjs +++ b/ui/tools/release-common.mjs @@ -276,6 +276,7 @@ export const CHECKLIST_ITEMS = [ "A Demo's Sample Library builds on this release: `just sample-library` prints what it holds.", '`just audit` is clean, or each advisory it reports is recorded in `deny.toml` with its reasoning.', "The agent image has Alpine's security fixes: if the Alpine release it is built on has published fixes for a package in it since it was last built, the bump branch edits the rebuild line in `agent-image/Dockerfile`.", + "Kamosu's image is built on the newest base images: the distroless runtime digest, Rust in the Dockerfile and `rust-toolchain.toml`, and the Node major.", '`THIRD_PARTY_NOTICES.md` matches the dependencies that ship.', 'The release title and notes are drafted.', ]; diff --git a/ui/tools/release-common.test.mjs b/ui/tools/release-common.test.mjs index 900e558b..21c2df09 100644 --- a/ui/tools/release-common.test.mjs +++ b/ui/tools/release-common.test.mjs @@ -167,7 +167,7 @@ test('a version field inside another Cargo.toml table is not the package version }); test('renders every item unticked', () => { - assert.equal(CHECKLIST_ITEMS.length, 10); + assert.equal(CHECKLIST_ITEMS.length, 11); assert.equal(renderChecklist(), CHECKLIST_ITEMS.map((item) => `- [ ] ${item}`).join('\n')); }); @@ -190,7 +190,7 @@ test('reads ticks, and reports edited or deleted items as missing', () => { assert.deepEqual(parsed.missing, [CHECKLIST_ITEMS[3], CHECKLIST_ITEMS[7]]); assert.deepEqual( parsed.items.map((item) => item.checked), - [true, true, false, false, false, false, false, false], + [true, true, false, false, false, false, false, false, false], ); });