Check builds use Docker's normal cache (closes #177)
check / check (push) Successful in 12s

Drop the CACHEBUST build argument from script/lint, script/test,
script/docker, script/cibuild and every Dockerfile stage. REPO_POLICIES
now says check builds use Docker's normal cache: an unchanged tree reuses
each step's stored result, which Docker keeps only for steps that
succeeded. The rules on placing ARG CACHEBUST and re-vendoring it in one
commit are gone; the rule that a planted defect proves a new or changed
check stays. The README, the Go style guide and both checklists restated
the cache-busting rules and are updated to match. The existing-repo
checklist asks that no script pass --no-cache or CACHEBUST.

Model: opus-5-5
This commit was merged in pull request #178.
This commit is contained in:
clawbot committed 2026-11-16 23:09:07 +01:00
1 parent 1ad7ae14be
commit 964d973e3c
10 files changed
+101 -260

No files matched your search

+43 -95
View File
@@ -1,6 +1,6 @@
---
title: Repository Policies
last_modified: 2026-11-09
last_modified: 2026-11-16
---
This document covers repository structure, tooling, and workflow standards. Code
@@ -254,10 +254,8 @@ style conventions are in separate documents:
phase and nothing else:
```sh
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--target lint --output type=cacheonly .
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--target test --output type=cacheonly .
docker build --target lint --output type=cacheonly .
docker build --target test --output type=cacheonly .
```
**A stage that is not the last one in the file is built only when the final
@@ -275,7 +273,8 @@ style conventions are in separate documents:
CI runner. `script/cibuild` and `script/docker` build the image that ships
and tag it, so each build replaces the previous image. Each script assigns
the tag on its own line before the build, so `set -e` stops it where
`script/projectname` fails.
`script/projectname` fails. `script/check` runs the two gate phases and
`script/fmt-check`, and builds no image of its own.
Inside a phase the tool is invoked directly: `golangci-lint`, `go test`,
`eslint`, `prettier`. The tool is never invoked through `make lint` or
@@ -298,48 +297,16 @@ style conventions are in separate documents:
- the settings
- the golangci-lint version
- **Any build that runs checks is given a new `CACHEBUST` value.** Docker
invalidates a `COPY` layer only when the copied content changes. On an
unchanged tree the check `RUN` is therefore served from cache, nothing
executes, and the build still exits 0. Every `docker build` in `script/`
therefore passes `--build-arg CACHEBUST="$(date +%s)-$$"`, the time and the
script's process id. So no two builds share a value, not even the three in one
`script/cibuild`. Four scripts do this, and there is no fifth:
- `script/lint`
- `script/test`
- `script/cibuild`
- `script/docker`
`script/check` runs the two gate phases and `script/fmt-check`, and builds
no image of its own. In every stage of the `Dockerfile`, every step that
lints, tests or compiles comes after `ARG CACHEBUST`. `ARG CACHEBUST` comes
right after these steps:
- the steps that install system packages
- the steps that download Go's modules
- the step that runs `script/bootstrap` to install a Python `test` phase's
packages from `Pipfile.lock`
A stage with none of these steps declares `ARG CACHEBUST` right after
`FROM`. A step that also installs anything else comes after `ARG CACHEBUST`
too. A `script/bootstrap` that also installs node packages is one. A new
value reruns every `RUN` step after that line; `COPY` steps are compared by
content and need nothing. Docker keeps the layers above the line until one
of these changes:
- **Check builds use Docker's normal cache.** On an unchanged tree Docker reuses
each step's stored result, and it stores a result only for a step that
succeeded. A step runs again when one of these changes:
- the base image
- their own lines
- the files they copy
- its own line or a line above it
- the files copied before it
A stage without the `ARG` line is served from cache on an unchanged tree, so
a repository re-vendors the scripts and adds the `ARG` lines in one commit.
The scripts do not pass `--no-cache`. That flag reruns every step too, but
it also builds the layers above the line again and empties every cache
mount. Go's build cache and golangci-lint's would then start empty every
time; the canonical Go `Dockerfile` below mounts them so that they survive
between check builds. A bare `docker build .` is not evidence that anything
ran: a sub-second build reporting success is a cache hit, not a result.
Never invalidate by pruning: `docker builder prune` and friends destroy a
build cache shared with every other build on the host. When a check is added
or changed, prove it works:
Nothing needs to run again on an unchanged tree. Never prune the build cache
(`docker builder prune` and the like): it is shared with every other build
on the host. When a check is added or changed, prove it works:
- plant a defect it must catch
- watch the run fail on it
- revert the defect
@@ -354,12 +321,8 @@ style conventions are in separate documents:
`Dockerfile`:
```dockerfile
# In every stage ARG CACHEBUST comes right after the steps that install
# system packages and download Go's modules, or right after FROM in a
# stage with neither, and every step that lints, tests or compiles
# comes after it. script/ passes a new value on every build, which
# reruns every RUN step after it. Docker keeps the layers above it
# until the base image, their own lines or go.mod and go.sum change.
# The steps that install system packages and download Go's modules
# come before COPY . ., so a change to the code keeps their layers.
# The steps that compile mount Go's build cache, and golangci-lint run
# also mounts golangci-lint's; both survive from build to build.
@@ -369,7 +332,6 @@ style conventions are in separate documents:
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
ARG CACHEBUST
COPY . .
RUN --mount=type=cache,target=/root/.cache/go-build \
--mount=type=cache,target=/root/.cache/golangci-lint \
@@ -385,7 +347,6 @@ style conventions are in separate documents:
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
ARG CACHEBUST
COPY . .
RUN --mount=type=cache,target=/root/.cache/go-build \
status=0; \
@@ -410,7 +371,6 @@ style conventions are in separate documents:
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
ARG CACHEBUST
COPY --from=lint /src/go.sum /dev/null
COPY --from=test /src/go.sum /dev/null
# A tar-stream context keeps the sender's file owners, which git refuses.
@@ -436,7 +396,6 @@ style conventions are in separate documents:
# Runtime stage, and the last one
FROM alpine@sha256:...
ARG CACHEBUST
COPY --from=builder /app /usr/local/bin/app
ENTRYPOINT ["app"]
```
@@ -452,15 +411,15 @@ style conventions are in separate documents:
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 above `ARG CACHEBUST`: 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. 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.
- 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
@@ -487,8 +446,8 @@ style conventions are in separate documents:
(`libvips-dev`, where alpine says `vips-dev`), and delete the package
lists in the same `RUN`, so the layer does not keep them. The test phase,
on the Debian Go image, installs the libraries its tests need the same
way. Either install goes right after `FROM`, above `ARG CACHEBUST`, so
Docker keeps it until the base image or the install line changes:
way. Either install goes right after `FROM`, so Docker keeps it until the
base image or the install line changes:
```dockerfile
FROM golangci/golangci-lint@sha256:... AS lint
@@ -498,7 +457,6 @@ style conventions are in separate documents:
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
ARG CACHEBUST
```
- `.dockerignore` lets `.git` into the build context. It keeps out every git
@@ -539,21 +497,19 @@ style conventions are in separate documents:
already do.
- **A Python `test` phase that installs its packages from `Pipfile.lock` does it
above `ARG CACHEBUST`, so check builds keep them.** The steps are:
before `COPY . .`, so check builds keep them.** The steps are:
- `COPY script/ script/`
- `COPY Pipfile Pipfile.lock ./`
- `RUN script/bootstrap`
`ARG CACHEBUST` comes right after them. Docker keeps what that `RUN`
installed until one of these changes:
Docker keeps what that `RUN` installed until one of these changes:
- the base image
- `script/`
- `Pipfile`
- `Pipfile.lock`
- a line up to and including the `RUN`
The tests run after `ARG CACHEBUST`, on every check build. In every other
stage, a step that installs Python packages comes after `ARG CACHEBUST`.
The tests run after `COPY . .`.
- When `script/bootstrap` runs in that step, it installs nothing beyond
these:
- system packages
@@ -561,8 +517,7 @@ style conventions are in separate documents:
- the packages from `Pipfile.lock`
`script/bootstrap` installs no Python there: the tests use the
distribution's Python, which a step above it installs. If it installs
anything else there, the step goes after `ARG CACHEBUST`.
distribution's Python, which a step above it installs.
- Debian's Python refuses a system-wide `pip install`, so pipenv goes in a
virtual environment at `$HOME/.pipenv`. `script/bootstrap` creates it with
@@ -644,7 +599,6 @@ style conventions are in separate documents:
COPY script/ script/
COPY Pipfile Pipfile.lock ./
RUN script/bootstrap
ARG CACHEBUST
COPY . .
RUN timeout 90 sh -c 'pipenv run pytest || { \
echo "--- Rerunning with -v for details ---"; \
@@ -663,20 +617,17 @@ style conventions are in separate documents:
A new push then cancels the older run on the same branch, queued or running,
and no other: runs for replaced commits do not hold up the shared runner.
`script/cibuild` bootstraps, runs the gate phases, and then builds the image,
so a successful run means every check passed. A bare `docker build .` does not
carry the same guarantee, because its gate phases may come from the cache. The
image build gets a `CACHEBUST` value of its own and so runs the gate phases a
second time. That is the price of the rule above, and it is worth paying. The
image that ships is built from a run of its own gates rather than from a cache
entry. The `check` job sets `timeout-minutes: 20`, so a hung build frees the
shared runner after 20 minutes. That allows for the three Docker builds
described above, each held to the 5-minute Docker build limit below, plus the
bootstrap. Those builds are the test phase, the lint phase, then the image. A
separate workflow limited to `main` by a `branches` list under `on: push`
cannot be checked by review. To try a change to it, add the feature branch to
that list and push, then remove the branch from the list again before merging.
Keep any job in it that publishes behind `if: github.ref_name == 'main'`, so
the run from the feature branch publishes nothing.
so a successful run means every check passed. The image build reuses the gate
phases that the check has just built. The `check` job sets
`timeout-minutes: 20`, so a hung build frees the shared runner after 20
minutes. That allows for the three Docker builds described above, each held to
the 5-minute Docker build limit below, plus the bootstrap. Those builds are
the test phase, the lint phase, then the image. A separate workflow limited to
`main` by a `branches` list under `on: push` cannot be checked by review. To
try a change to it, add the feature branch to that list and push, then remove
the branch from the list again before merging. Keep any job in it that
publishes behind `if: github.ref_name == 'main'`, so the run from the feature
branch publishes nothing.
- Use platform-standard formatters:
- `black` for Python
@@ -787,8 +738,7 @@ style conventions are in separate documents:
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 new
`CACHEBUST` value (above) is what makes that step run on an unchanged tree.
check builds, so the phase's `go test` runs carry `-count=1` too.
Python example:
@@ -891,9 +841,7 @@ style conventions are in separate documents:
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
[ -n "$version" ] || version="unknown"
tag="$(script/projectname)"
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--build-arg VERSION="$version" \
-t "$tag" .
docker build --build-arg VERSION="$version" -t "$tag" .
```
`--always` makes an untagged repo yield an abbreviated commit hash rather