From e3f3160fad0992f2f58cb42cb692f8aa844e6572 Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Mon, 16 Nov 2026 23:43:40 +0000 Subject: [PATCH] REPO_POLICIES: Canonical Go Dockerfile Cuts the Go make test recipe, which repeats the command in examples/go.Dockerfile, and turns its notes into three key points; drops key points stated elsewhere (the no-op copies and the last stage under Dockerfile, when Docker installs again under Docker's cache, the Python layer under the Python section) and "BuildKit runs stages in parallel"; every rule stays. Model: opus-5-5 --- prompts/REPO_POLICIES.md | 96 +++++++++++++--------------------------- 1 file changed, 30 insertions(+), 66 deletions(-) diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index 90bc545..d1a1879 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -388,38 +388,26 @@ style conventions are in separate documents: A green run alone shows neither that the check ran nor that it covers what it should. +## Canonical Go `Dockerfile` + - **The gate phases are separate stages, and the build stage depends on both.** The lint phase is based on the `golangci/golangci-lint` image (pinned by hash), so lint failures surface in seconds rather than after a full compile. - The test phase is based on the Debian Go image. The canonical Go repo - `Dockerfile` is at - `https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go.Dockerfile`. + That image has both Go and the linter, so nothing needs installing. The test + phase is based on the Debian Go image. + + The canonical Go `Dockerfile` is at + `https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go.Dockerfile`. Key points: - - The lint phase uses the `golangci/golangci-lint` image directly, so - nothing needs installing: it has both Go and the linter. - - `COPY --from= /src/go.sum /dev/null` is a no-op copy whose only - purpose is the dependency on that phase. BuildKit runs stages in parallel - by default, and a stage nothing depends on is not built at all. Without - these two lines a red gate would not fail the build. - - Keep the runtime stage last. If you add a stage after it, give it the same - two copies. A plain `docker build .` builds the last stage's chain and - nothing else. - Check builds keep these, and none of them can hand back a stale result: - - The layers of the system packages and Go's modules. Docker installs - the packages again when the base image or the install line changes. - Docker downloads the modules again when `go.mod` or `go.sum` changes. - Go checks every module against `go.sum` as it downloads it, and no - later build can change a kept layer. The modules are kept in a layer - rather than a cache mount. A cache mount is shared by every build on - the host, and Go builds from whatever files the mount holds without - checking them again (only `go mod verify` does). A file changed there - would go unnoticed. + - The layers of the system packages and Go's modules. Go checks every + module against `go.sum` as it downloads it, and no later build can + change a kept layer. - Go's build cache (`/root/.cache/go-build`, where Go keeps it for root), mounted on the steps that compile: `golangci-lint run`, both `go test` runs and `go build`. Go reuses a compiled package only when - all its inputs are unchanged. The cache also holds test results, which - is why both `go test` runs carry `-count=1`. + all its inputs are unchanged. - golangci-lint's cache (`/root/.cache/golangci-lint`, where the pinned image keeps it), mounted on `golangci-lint run`. golangci-lint reuses a package's findings only when all of these are unchanged: @@ -427,9 +415,10 @@ style conventions are in separate documents: - `go.mod` - the linters and their settings in `.golangci.yml` - the golangci-lint version - - In a Python `test` phase, the layer of the step that runs - `script/bootstrap` to install the packages from `Pipfile.lock`, as - described for that phase below. + - The modules are kept in a layer rather than a cache mount. A cache mount + is shared by every build on the host, and Go builds from whatever files + the mount holds without checking them again (only `go mod verify` does). A + file changed there would go unnoticed. - If the project uses `//go:embed` directives that reference build artifacts, the lint phase must create placeholder files so the embed directives resolve. A web frontend compiled in a separate stage is such an @@ -445,46 +434,21 @@ style conventions are in separate documents: base image or the install line changes. The first lines of a lint phase that installs system libraries are at `https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go-lint-system-libraries.Dockerfile`. - - Go example: - - ```makefile - test: - @status=0; \ - output=$$(go test -count=1 -timeout 90s -race -cover ./... 2>&1) || status=$$?; \ - printf '%s\n' "$$output"; \ - test "$$status" -eq 0 && exit 0; \ - case "$$output" in \ - *"panic: test timed out"*|*"*** Test killed"*) exit 1 ;; \ - esac; \ - echo "--- Rerunning with -v for details ---"; \ - go test -count=1 -timeout 90s -race -v ./...; \ - exit 1 - ``` - - The first run's output is kept so that the recipe can look in it for what Go - prints for a hang: - - `panic: test timed out` means the test's own timer fired. - - `*** Test killed` means `go test` stopped a test that ignored that timer, - about a minute later. - - Go prints the goroutine stacks with either line, as long as the test can - still respond. A rerun would only wait for the same hang, so the recipe - exits 1. A failure with neither line in its output reruns with `-v`. The - kept output prints when the first run ends, not while it runs. - - `-count=1` is required on both invocations. It defeats Go's test _result_ - cache, so neither run can report a stored pass in place of running the - tests. It leaves the build cache alone, so it costs the runtime of the suite - and no recompilation. - - That cache is Go's own, separate from Docker's layer cache. Go stores a - passing result in its cache directory (`GOCACHE`). When the same tests run - again on unchanged code, it prints that result, marked `(cached)`, without - running them. The directory lasts from one run to the next on a developer's - machine, where this target runs. The directory also lasts in the `test` - phase of the `Dockerfile`, which mounts it to keep compiled packages between - check builds, so the phase's `go test` runs carry `-count=1` too. + - The test command keeps the first run's output, to look in it for what Go + prints for a hang. `panic: test timed out` means the test's own timer + fired. `*** Test killed` means `go test` stopped a test that ignored that + timer, about a minute later. Go prints the goroutine stacks with either + line, as long as the test can still respond. On either line the command + exits 1 without a rerun. A failure with neither line reruns with `-v`. The + kept output prints when the first run ends, not while it runs. + - `-count=1` is required on both `go test` invocations. Go stores a passing + result in its cache directory (`GOCACHE`). When the same tests run again + on unchanged code, it prints that result, marked `(cached)`, without + running them. That directory lasts between runs on a developer's machine, + and in the `test` phase, which mounts it to keep compiled packages. + - `-count=1` defeats only that test _result_ cache. It leaves the build + cache alone, so it costs the runtime of the suite and no recompilation. + The cache is Go's own, separate from Docker's layer cache. - **A Python `test` phase that installs its packages from `Pipfile.lock` does it before `COPY . .`, so check builds keep them.** The steps are: