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

Cuts history ("Both have produced wrong verdicts"), an example given
for a stated reason (the Go image's toolchain), the tag sentence that
the version snippet's comment states, and the short cache list that
the Go section gives in full; takes in the rule to keep the stage that
ships last, which the Go section's commit removes; every rule stays.

Model: opus-5-5
This commit is contained in:
clawbot committed 2026-11-16 23:41:36 +00:00
1 parent e13195dd84
commit 99c8e425da
1 file changed
+26 -29
+26 -29
View File
@@ -306,6 +306,8 @@ style conventions are in separate documents:
a `go.mod` tool dependency or through a `tools.go` file, either of which
pulls the tool's own dependencies into the repo's `go.mod` and `go.sum`.
# Dockerfile
- Every repo should have a `Dockerfile`, and it carries the repo's gates: a
`lint` phase and a `test` phase. The final stage depends on both, so the image
cannot be built unless they pass. For non-server repos the final stage brings
@@ -320,9 +322,8 @@ style conventions are in separate documents:
running `script/bootstrap`. Only system packages may be installed inline
above it, so that check builds keep them; the `prompts` repo's own
`Dockerfile` does this. A stage that runs `script/bootstrap` COPYs `script/`
and the dependency manifests it needs before running it. These are examples:
- `package.json`, `yarn.lock`, `.yarnrc.yml` and `.yarn/releases/`
- `go.mod` and `go.sum`
and the dependency manifests it needs before running it: `go.mod` and
`go.sum`, for example, or the four yarn files named above.
- **The lint and test gates run in Docker, as phases of the `Dockerfile`.**
There is no separate lint file. `script/lint` and `script/test` each build one
@@ -336,41 +337,37 @@ style conventions are in separate documents:
**A stage that is not the last one in the file is built only when the final
stage's chain depends on it, or when `--target` names it.** That is why the
two gates are always invoked by name here, and why the final stage carries a
`COPY --from=` of a harmless file from each of them. Without that
dependency, a plain `docker build .` builds the last stage alone and exits 0
having linted and tested nothing.
`COPY --from=` of a harmless file from each of them. Without those copies, a
plain `docker build .` builds the last stage's chain alone and exits 0
having linted and tested nothing. Keep the stage that ships last: the
runtime image, or the development environment in a non-server repo. If you
add a stage after it, give it the same two copies.
**The gate builds write no image.** With `--output type=cacheonly` the phase
runs and a failing step fails the build, but the result is not exported.
Nothing uses those images, and writing one out is slow: a Go test phase's
image holds the toolchain. A build given neither `--output` nor `-t` writes
an untagged image and leaves it dangling, on every developer host and every
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/check` runs the two gate phases and
`script/fmt-check`, and builds no image of its own.
Nothing uses those images, and writing one out is slow. A build given
neither `--output` nor `-t` leaves an untagged image dangling on every
developer host and CI runner. `script/cibuild` and `script/docker` tag the
image that ships, so each build replaces the previous image. `script/check`
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
`script/test`. Those are themselves a `docker build`, and would recurse into
a daemon that does not exist in a build step. Formatting is the exception
and stays on the host: `script/fmt` writes the working tree, and
`script/fmt-check` is its read-only twin.
**Inside a phase the tool is invoked directly:** `golangci-lint`, `go test`,
`eslint`, `prettier`. It is never invoked through `make lint` or
`script/test`, which are themselves a `docker build` and would recurse into
a daemon that does not exist in a build step.
**Formatting is the exception and stays on the host.** `script/fmt` writes
the working tree, and `script/fmt-check` is its read-only twin.
**No lint verdict may come from a host invocation of the linter.** On a
shared host golangci-lint reads a result cache keyed on file content rather
than location. A second checkout of the same content is therefore served the
first one's findings. A host-global lock in `$TMPDIR` also makes concurrent
runs exit non-zero with `parallel golangci-lint is running`, a status a
caller cannot tell from real findings. Both have produced wrong verdicts in
this org, in both directions. A container has its own `TMPDIR`, so the lock
is out of reach. The lint phase does keep golangci-lint's cache between
check builds (below), but it lints every checkout at `/src`. A finding is
taken from that cache only when all of these are the same:
- the files
- the settings
- the golangci-lint version
runs exit non-zero with `parallel golangci-lint is running`, which a caller
cannot tell from real findings. A container has its own `TMPDIR`, out of the
lock's reach. The lint phase does keep golangci-lint's cache between check
builds, but it lints every checkout at `/src`. It reuses a finding only on
the conditions listed under the canonical Go `Dockerfile` below.
- **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