REPO_POLICIES: Canonical Go Dockerfile
check / check (push) Canceled after 0s

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
This commit is contained in:
clawbot committed 2026-11-16 23:43:40 +00:00
1 parent c166d20195
commit e3f3160fad
1 file changed
+30 -66
+30 -66
View File
@@ -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=<phase> /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: