Compare commits
1 Commits
51c394552e
...
6b9827a618
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
6b9827a618 |
@@ -92,18 +92,14 @@ style conventions are in separate documents:
|
||||
reading the Makefile.
|
||||
|
||||
- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
|
||||
as a build step so the build fails if the branch is not green — which requires
|
||||
`ARG CHECK_EPOCH` and its guard in every stage containing a check-running
|
||||
`RUN`, per the `CHECK_EPOCH` rule below. Without them a Dockerfile satisfies
|
||||
this criterion while its check layers are served from cache, so the build
|
||||
cannot fail on a branch that is not green. For non-server repos, the
|
||||
Dockerfile should bring up a development environment and run `make check`. For
|
||||
server repos, `make check` should run as an early build stage before the final
|
||||
image is assembled. Dockerfiles install development prerequisites by running
|
||||
`script/bootstrap` rather than duplicating installs inline; COPY `script/` and
|
||||
the dependency manifests (`package.json` + `yarn.lock`, `go.mod` + `go.sum`,
|
||||
etc.) before running it so the bootstrap layer stays cached until dependencies
|
||||
change.
|
||||
as a build step so the build fails if the branch is not green. For non-server
|
||||
repos, the Dockerfile should bring up a development environment and run
|
||||
`make check`. For server repos, `make check` should run as an early build
|
||||
stage before the final image is assembled. Dockerfiles install development
|
||||
prerequisites by running `script/bootstrap` rather than duplicating installs
|
||||
inline; COPY `script/` and the dependency manifests (`package.json` +
|
||||
`yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
|
||||
layer stays cached until dependencies change.
|
||||
|
||||
- **Every check-running `RUN` must be cache-busted with `CHECK_EPOCH`.** Docker
|
||||
invalidates a `COPY` layer only when the copied content changes, so on an
|
||||
@@ -134,8 +130,8 @@ style conventions are in separate documents:
|
||||
rather than dependent on BuildKit's handling of an unreferenced `ARG`, and
|
||||
it puts the epoch in the build log. The guard is itself value-keyed, for
|
||||
the same reason: it references `$CHECK_EPOCH`, so BuildKit renders the
|
||||
epoch into that layer's description (rendered as
|
||||
`RUN [ -n "<epoch>" ] || exit 1`) and re-runs it whenever the value
|
||||
epoch into that layer's description (observed as
|
||||
`RUN [ -n "1786287053..." ] || exit 1`) and re-runs it whenever the value
|
||||
changes. Each stage therefore has two independent invalidation points, and
|
||||
the guard always precedes the check `RUN`. Keep both: the expansion is
|
||||
defence in depth, and it is what makes the epoch visible in the build
|
||||
@@ -216,16 +212,6 @@ style conventions are in separate documents:
|
||||
a stage dependency. BuildKit runs stages in parallel by default; without
|
||||
this line, the build stage would not wait for lint to finish and a lint
|
||||
failure might not fail the overall build.
|
||||
- **Re-prove that ordering on a warm cache after adopting `CHECK_EPOCH`.**
|
||||
The cache-bust turns this no-op `COPY` into a content-cache hit, so an
|
||||
ordering guarantee established on a cold cache does not automatically
|
||||
carry over; it has to be re-checked warm. This was re-proved in another
|
||||
repo in the org that uses the same file-dependency trick (there with a
|
||||
marker file in place of `go.sum`), and the ordering held. It has **not**
|
||||
been verified in this repo, which is single-stage and has no lint stage to
|
||||
order against. Any repo relying on a file-dependency trick for stage
|
||||
ordering should re-check it warm after adopting the bust rather than
|
||||
assuming this result transfers.
|
||||
- If the project uses `//go:embed` directives that reference build artifacts
|
||||
(e.g. a web frontend compiled in a separate stage), the lint stage must
|
||||
create placeholder files so the embed directives resolve. Example:
|
||||
|
||||
Reference in New Issue
Block a user