From 90e5a1f5d047405f365a14c6b226639f43674f97 Mon Sep 17 00:00:00 2001 From: Joakim Persson Date: Wed, 20 May 2026 23:11:57 +0200 Subject: [PATCH] AGENTS.md: documentation-drift sweep as explicit pre-commit step Companion to the same addition in the cloud-init and ansible repos. Caught real drift in those repos in a recent session only because the user explicitly asked. Codify the sweep with concrete, repo- specific drift hotspots rather than a vague 'watch for drift' rule that gets ignored. Each AGENTS.md addition lists the doc files most likely to fall behind code changes here, plus a quick-triage one-liner using 'git diff --name-only HEAD | xargs grep -l ...' so the rule is actionable not aspirational. --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e9e3cef..f045cf1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,6 +43,8 @@ When bumping the opencode version, bump `OPENCODE_VERSION` in `Dockerfile.varian - `.env.example` must be hand-updated to match Dockerfile/entrypoint behavior — it is not auto-generated. Release-day checklist: README → (regenerate DOCKER_HUB.md only if HUB_TEMPLATE changed) → promote CHANGELOG Unreleased → grep AGENTS.md for stale counts → commit → tag → push tag. + + **Between releases the same coupling applies.** Doc drift is not just a release-day concern — a workflow tweak, entrypoint change, or `generate-config.py` refactor can leave any of these four files lying. Before committing a non-release change, grep the docs for references to what you touched: `git diff --name-only HEAD | xargs -I{} grep -l 'thing-you-changed' README.md AGENTS.md DOCKER_HUB.md .gitea/README.md .env.example`. If a doc says "four variants" / "two phases" / "runs on amd64 only" and your change made that no longer true, fix it in the same commit. - **GitHub/Gitea-sourced binaries float by default** — gosu, fzf, git-lfs, nvim, bat, eza, zoxide, uv, gitea-mcp, Go, oh-my-opencode-slim all default to `latest`. Each build-time install step reads the `/releases/latest` Location redirect (or the go.dev JSON feed for Go) and derives the concrete version. Use the same `ARCH` case-switch pattern for multi-arch support (amd64/arm64). Intentional pins: `OPENCODE_VERSION` (drives the image tag), `NODE_VERSION=22` (major pin), `DEBIAN_VERSION=trixie-slim` (OS base). Adding a new upstream tool: follow the existing floated-version pattern, don't hardcode a specific tag. - **Resolved versions are logged by the smoke test** — `scripts/smoke-test.sh` prints a "Resolved component versions" table as its first step. CI logs always capture what got baked into a given image even when ARGs default to `latest`. - **Shell scripts use `set -euo pipefail`** — both entrypoints are strict. Errors in volume chown or SSH permission operations are intentionally suppressed with `|| true`.