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:
1 parent
1ad7ae14be
commit
964d973e3c
10 files changed
+101
-260
No files matched your search
+43
-95
@@ -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
|
||||
|
||||
Reference in new issue
Block a user