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
+28 -64
+28 -64
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 A green run alone shows neither that the check ran nor that it covers what
it should. it should.
## Canonical Go `Dockerfile`
- **The gate phases are separate stages, and the build stage depends on both.** - **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 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. 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 That image has both Go and the linter, so nothing needs installing. The test
`Dockerfile` is at 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`. `https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go.Dockerfile`.
Key points: 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: - 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 layers of the system packages and Go's modules. Go checks every
the packages again when the base image or the install line changes. module against `go.sum` as it downloads it, and no later build can
Docker downloads the modules again when `go.mod` or `go.sum` changes. change a kept layer.
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.
- Go's build cache (`/root/.cache/go-build`, where Go keeps it for - Go's build cache (`/root/.cache/go-build`, where Go keeps it for
root), mounted on the steps that compile: `golangci-lint run`, both root), mounted on the steps that compile: `golangci-lint run`, both
`go test` runs and `go build`. Go reuses a compiled package only when `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 all its inputs are unchanged.
is why both `go test` runs carry `-count=1`.
- golangci-lint's cache (`/root/.cache/golangci-lint`, where the pinned - golangci-lint's cache (`/root/.cache/golangci-lint`, where the pinned
image keeps it), mounted on `golangci-lint run`. golangci-lint reuses image keeps it), mounted on `golangci-lint run`. golangci-lint reuses
a package's findings only when all of these are unchanged: a package's findings only when all of these are unchanged:
@@ -427,9 +415,10 @@ style conventions are in separate documents:
- `go.mod` - `go.mod`
- the linters and their settings in `.golangci.yml` - the linters and their settings in `.golangci.yml`
- the golangci-lint version - the golangci-lint version
- In a Python `test` phase, the layer of the step that runs - The modules are kept in a layer rather than a cache mount. A cache mount
`script/bootstrap` to install the packages from `Pipfile.lock`, as is shared by every build on the host, and Go builds from whatever files
described for that phase below. 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 - If the project uses `//go:embed` directives that reference build
artifacts, the lint phase must create placeholder files so the embed artifacts, the lint phase must create placeholder files so the embed
directives resolve. A web frontend compiled in a separate stage is such an 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 base image or the install line changes. The first lines of a lint phase
that installs system libraries are at that installs system libraries are at
`https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go-lint-system-libraries.Dockerfile`. `https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go-lint-system-libraries.Dockerfile`.
- The test command keeps the first run's output, to look in it for what Go
Go example: 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
```makefile timer, about a minute later. Go prints the goroutine stacks with either
test: line, as long as the test can still respond. On either line the command
@status=0; \ exits 1 without a rerun. A failure with neither line reruns with `-v`. The
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. 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
`-count=1` is required on both invocations. It defeats Go's test _result_ result in its cache directory (`GOCACHE`). When the same tests run again
cache, so neither run can report a stored pass in place of running the on unchanged code, it prints that result, marked `(cached)`, without
tests. It leaves the build cache alone, so it costs the runtime of the suite running them. That directory lasts between runs on a developer's machine,
and no recompilation. and in the `test` phase, which mounts it to keep compiled packages.
- `-count=1` defeats only that test _result_ cache. It leaves the build
That cache is Go's own, separate from Docker's layer cache. Go stores a cache alone, so it costs the runtime of the suite and no recompilation.
passing result in its cache directory (`GOCACHE`). When the same tests run The cache is Go's own, separate from Docker's layer cache.
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.
- **A Python `test` phase that installs its packages from `Pipfile.lock` does it - **A Python `test` phase that installs its packages from `Pipfile.lock` does it
before `COPY . .`, so check builds keep them.** The steps are: before `COPY . .`, so check builds keep them.** The steps are: