prompts/NEW_REPO_CHECKLIST.md

@@ -112,7 +112,8 @@ Template files can be fetched from:
       `script/` builds pass a new `CACHEBUST` value on every build, which reruns
       every `RUN` step and keeps Go's build cache; `--no-cache` would empty it.
       A stage without the `ARG` line is served from cache on an unchanged tree,
-      so the scripts and the `ARG` lines are re-vendored in one commit.
+      so the scripts and every stage's `ARG CACHEBUST` line are added in the
+      same commit.
     - Go: the steps that compile (`golangci-lint run`, `go test`, `go build`)
       mount Go's build cache (`--mount=type=cache,target=/root/.cache/go-build`)
       and nothing else, and both `go test` runs carry `-count=1`, as in the

prompts/REPO_POLICIES.md

@@ -139,12 +139,12 @@ style conventions are in separate documents:
     **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 and every compiled package. A build given neither
+    image holds the toolchain. A build given neither `--output` nor `-t` writes
-    `--output` nor `-t` writes an untagged image and leaves it dangling, on
+    an untagged image and leaves it dangling, on every developer host and every
-    every developer host and every CI runner. `script/cibuild` and
+    CI runner. `script/cibuild` and `script/docker` build the image that ships
-    `script/docker` build the image that ships and tag it, so each build
+    and tag it, so each build replaces the previous image; each assigns the tag
-    replaces the previous image; each assigns the tag on its own line before the
+    on its own line before the build, so `set -e` stops it where
-    build, so `set -e` stops it where `script/projectname` fails.
+    `script/projectname` fails.
 
     Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
     `eslint`, `prettier` — never through `make lint` or `script/test`, which are

script/cibuild

@@ -4,6 +4,9 @@
 # the formatter on the host, which a pristine checkout cannot do.
 # A new CACHEBUST value reruns every RUN step, since a cached gate phase
 # is a check that did not run; unlike --no-cache, it keeps Go's build cache.
+# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
+# first; a stage without that line is served from cache on an unchanged
+# tree, with no warning.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/docker

@@ -3,6 +3,9 @@
 # Identical in all repos; the tag comes from script/projectname.
 # A new CACHEBUST value reruns every RUN step, since a cached gate phase
 # is a check that did not run; unlike --no-cache, it keeps Go's build cache.
+# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
+# first; a stage without that line is served from cache on an unchanged
+# tree, with no warning.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/lint

@@ -7,8 +7,10 @@
 # The phase is not the last stage in the file, so it is built only when
 # --target names it. A new CACHEBUST value reruns every RUN step, since
 # a cached lint layer is a lint that did not run; unlike --no-cache, it
-# keeps Go's build cache. --output type=cacheonly writes no image, since
+# keeps Go's build cache. This relies on every stage of the Dockerfile
-# nothing uses one.
+# declaring ARG CACHEBUST first; a stage without that line is served
+# from cache on an unchanged tree, with no warning.
+# --output type=cacheonly writes no image, since nothing uses one.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/test

@@ -3,8 +3,11 @@
 # and this builds that phase alone, on the same terms as script/lint:
 # --target because a phase that is not the last stage is built only when
 # named, and a new CACHEBUST value because a cached test layer is a test
-# that did not run; unlike --no-cache, it keeps Go's build cache.
+# that did not run; unlike --no-cache, it keeps Go's build cache. This
-# --output type=cacheonly writes no image, since nothing uses one.
+# relies on every stage of the Dockerfile declaring ARG CACHEBUST first;
+# a stage without that line is served from cache on an unchanged tree,
+# with no warning. --output type=cacheonly writes no image, since
+# nothing uses one.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"