Compare commits
8
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
29dcf38205 | ||
|
|
964d973e3c | ||
|
|
1ad7ae14be | ||
|
|
69d38ba6de | ||
|
|
198b896a53 | ||
|
|
11245b85ca | ||
|
|
02632a5682 | ||
|
|
fdf517a1f7 |
No files matched your search
@@ -1,7 +1,2 @@
|
|||||||
# Every PR adds an entry at the top of TODO.md's Completed Steps; union keeps
|
|
||||||
# both sides instead of conflicting. Git never reports a conflict here: read
|
|
||||||
# the merged entries after every merge or rebase.
|
|
||||||
TODO.md merge=union
|
|
||||||
|
|
||||||
# yarn's release file is one opaque file in diffs and merges.
|
# yarn's release file is one opaque file in diffs and merges.
|
||||||
.yarn/releases/** binary
|
.yarn/releases/** binary
|
||||||
+4
-10
@@ -2,18 +2,14 @@
|
|||||||
# lint` or `script/lint`, which are themselves a docker build and would
|
# lint` or `script/lint`, which are themselves a docker build and would
|
||||||
# recurse into a daemon that does not exist in a build step.
|
# recurse into a daemon that does not exist in a build step.
|
||||||
#
|
#
|
||||||
# In every stage, ARG CACHEBUST comes right after the step that installs
|
# node and yarn come from the distribution, which is trusted, so they
|
||||||
# system packages. script/ passes a new value on every build. That value
|
# need no version and no hash. That yarn only starts the release file in
|
||||||
# reruns every RUN step below the ARG line, and the install step keeps
|
# .yarn/releases/, so every stage copies that file and .yarnrc.yml
|
||||||
# its layer. node and yarn come from the distribution, which is trusted,
|
# before it runs script/bootstrap.
|
||||||
# so they need no version and no hash. That yarn only starts the release
|
|
||||||
# file in .yarn/releases/, so every stage copies that file and
|
|
||||||
# .yarnrc.yml before it runs script/bootstrap.
|
|
||||||
#
|
#
|
||||||
# alpine 3.24.3, 2026-11-04
|
# alpine 3.24.3, 2026-11-04
|
||||||
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS lint
|
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS lint
|
||||||
RUN apk add --no-cache git make nodejs-current yarn
|
RUN apk add --no-cache git make nodejs-current yarn
|
||||||
ARG CACHEBUST
|
|
||||||
|
|
||||||
WORKDIR /app
|
WORKDIR /app
|
||||||
|
|
||||||
@@ -31,7 +27,6 @@ RUN yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
|
|||||||
# alpine 3.24.3, 2026-11-04
|
# alpine 3.24.3, 2026-11-04
|
||||||
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS test
|
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS test
|
||||||
RUN apk add --no-cache git make nodejs-current yarn
|
RUN apk add --no-cache git make nodejs-current yarn
|
||||||
ARG CACHEBUST
|
|
||||||
|
|
||||||
WORKDIR /app
|
WORKDIR /app
|
||||||
|
|
||||||
@@ -53,7 +48,6 @@ RUN timeout 90 test/update-policy.sh
|
|||||||
# alpine 3.24.3, 2026-11-04
|
# alpine 3.24.3, 2026-11-04
|
||||||
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
|
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
|
||||||
RUN apk add --no-cache git make nodejs-current yarn
|
RUN apk add --no-cache git make nodejs-current yarn
|
||||||
ARG CACHEBUST
|
|
||||||
|
|
||||||
WORKDIR /app
|
WORKDIR /app
|
||||||
|
|
||||||
|
|||||||
@@ -116,12 +116,10 @@ alpine. We provide:
|
|||||||
`script/bootstrap`, then `script/install-precommit`
|
`script/bootstrap`, then `script/install-precommit`
|
||||||
- `script/projectname` — output the project name (our own extension); used by
|
- `script/projectname` — output the project name (our own extension); used by
|
||||||
`script/docker` for the image tag
|
`script/docker` for the image tag
|
||||||
- `script/test` —
|
- `script/test` — `docker build --target test --output type=cacheonly .`,
|
||||||
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target test --output type=cacheonly .`,
|
|
||||||
building the `test` phase of the `Dockerfile`, which runs
|
building the `test` phase of the `Dockerfile`, which runs
|
||||||
`test/update-policy.sh`, without writing an image
|
`test/update-policy.sh`, without writing an image
|
||||||
- `script/lint` —
|
- `script/lint` — `docker build --target lint --output type=cacheonly .`,
|
||||||
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target lint --output type=cacheonly .`,
|
|
||||||
building the `lint` phase, which runs prettier over the markdown files,
|
building the `lint` phase, which runs prettier over the markdown files,
|
||||||
without writing an image
|
without writing an image
|
||||||
- `script/fmt` — format all markdown files with prettier (writes; native, not in
|
- `script/fmt` — format all markdown files with prettier (writes; native, not in
|
||||||
@@ -129,14 +127,13 @@ alpine. We provide:
|
|||||||
- `script/fmt-check` — check formatting (read-only; native)
|
- `script/fmt-check` — check formatting (read-only; native)
|
||||||
- `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
|
- `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
|
||||||
extension); builds no image of its own
|
extension); builds no image of its own
|
||||||
- `script/docker` —
|
- `script/docker` — `docker build --build-arg VERSION="$version" -t prompts .`,
|
||||||
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t prompts .`,
|
|
||||||
the tag coming from `script/projectname` (byte-identical across repos)
|
the tag coming from `script/projectname` (byte-identical across repos)
|
||||||
- `script/cibuild` — cd to the repo root, run `script/bootstrap`, run
|
- `script/cibuild` — cd to the repo root, run `script/bootstrap`, run
|
||||||
`script/check`, compute `version` from `git describe`, then
|
`script/check`, compute `version` from `git describe`, then
|
||||||
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t prompts .`
|
`docker build --build-arg VERSION="$version" -t prompts .` (what CI runs; it
|
||||||
(what CI runs; it bootstraps because CI checks out and runs this alone while
|
bootstraps because CI checks out and runs this alone while `script/fmt-check`
|
||||||
`script/fmt-check` is native)
|
is native)
|
||||||
- `script/precommit` — run by the git pre-commit hook (our own extension); calls
|
- `script/precommit` — run by the git pre-commit hook (our own extension); calls
|
||||||
`script/check`
|
`script/check`
|
||||||
- `script/install-precommit` — installs the git pre-commit hook (our own
|
- `script/install-precommit` — installs the git pre-commit hook (our own
|
||||||
@@ -147,23 +144,6 @@ alpine. We provide:
|
|||||||
|
|
||||||
`make hooks` installs the pre-commit hook that runs `script/precommit`.
|
`make hooks` installs the pre-commit hook that runs `script/precommit`.
|
||||||
|
|
||||||
In every stage of a `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`.
|
|
||||||
The `script/` builds pass a new `CACHEBUST` value on every build, which reruns
|
|
||||||
every `RUN` step after that line and leaves the layers above it and the cache
|
|
||||||
mounts in place; `--no-cache` would build those layers again and empty the
|
|
||||||
mounts. This repo's own `Dockerfile` installs git, make, node and yarn right
|
|
||||||
after `FROM` in every stage, above `ARG CACHEBUST`. `script/bootstrap` installs
|
|
||||||
the node packages below that line, because check builds keep system packages but
|
|
||||||
not node packages.
|
|
||||||
|
|
||||||
## Rationale
|
## Rationale
|
||||||
|
|
||||||
LLM prompts, especially development policies, benefit from version control and a
|
LLM prompts, especially development policies, benefit from version control and a
|
||||||
@@ -177,22 +157,6 @@ subdirectory. Each file contains one or more related prompts or policy
|
|||||||
documents. There is no build step or runtime component; the prompts are consumed
|
documents. There is no build step or runtime component; the prompts are consumed
|
||||||
by copying them into other projects or referencing them directly.
|
by copying them into other projects or referencing them directly.
|
||||||
|
|
||||||
## Template Repos
|
|
||||||
|
|
||||||
These template repositories implement the policies defined in this repo and
|
|
||||||
serve as starting points for new projects. They must be kept in sync when
|
|
||||||
policies change.
|
|
||||||
|
|
||||||
- **[template-app-go](https://git.eeqj.de/sneak/template-app-go)** — Go HTTP
|
|
||||||
server template (Uber fx, chi, SQLite, session auth, Prometheus metrics)
|
|
||||||
- **[template-app-js](https://git.eeqj.de/sneak/template-app-js)** — JavaScript
|
|
||||||
SPA template (Vite, Tailwind CSS v4, nginx Docker deployment)
|
|
||||||
- **[template-app-python](https://git.eeqj.de/sneak/template-app-python)** —
|
|
||||||
Python web application template (FastAPI, uvicorn, pytest, black, ruff)
|
|
||||||
|
|
||||||
When updating policies in this repo, also update the template repos to match
|
|
||||||
(Makefile targets, Dockerfile conventions, CI workflows, required files, etc.).
|
|
||||||
|
|
||||||
## See Also
|
## See Also
|
||||||
|
|
||||||
- **[clawpub](https://git.eeqj.de/sneak/clawpub)** — Real-world examples,
|
- **[clawpub](https://git.eeqj.de/sneak/clawpub)** — Real-world examples,
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
- branch (from `main`)
|
- branch (from `main`)
|
||||||
- do the work in Next Step
|
- do the work in Next Step
|
||||||
- move Next Step to the top of Completed Steps
|
- delete Next Step from `TODO.md`
|
||||||
- move the top item of Future Steps into Next Step
|
- move the top item of Future Steps into Next Step
|
||||||
- commit (`TODO.md` changes in the same commit as the work)
|
- commit (`TODO.md` changes in the same commit as the work)
|
||||||
- merge to `main` if the branch is not protected, otherwise open a PR
|
- merge to `main` if the branch is not protected, otherwise open a PR
|
||||||
@@ -19,434 +19,8 @@ prompts/FIXUP_CLEAN.md (currently a near-empty stub) and prompts/FIXUP_REPORT.md
|
|||||||
(a rough draft). Write the missing content, run `make fmt` so they pass
|
(a rough draft). Write the missing content, run `make fmt` so they pass
|
||||||
fmt-check, and commit.
|
fmt-check, and commit.
|
||||||
|
|
||||||
# Completed Steps
|
|
||||||
|
|
||||||
- 2026-11-09: `script/update-policy` and `make update-policy` update a repo's
|
|
||||||
vendored policy files with one command
|
|
||||||
(https://git.eeqj.de/sneak/prompts/issues/162). They fetch the files from
|
|
||||||
`prompts`, keep the repo's own entries, commit and push. The canonical
|
|
||||||
`.dockerignore` now ends with the comment that the repo's own entries go
|
|
||||||
below. The template repositories get the script in their own issues.
|
|
||||||
- 2026-11-07: Go code is now formatted with `gofmt` and then `golines -m 77`
|
|
||||||
(https://git.eeqj.de/sneak/prompts/issues/160). `prompts/REPO_POLICIES.md`
|
|
||||||
says how `script/fmt`, `script/fmt-check` and `script/bootstrap` do it and
|
|
||||||
pins `golines`. The Go style guide and both checklists say the same. `lll`
|
|
||||||
stays at 88, since `golines` leaves long strings and comments as they are.
|
|
||||||
- 2026-11-06: The pinning rule in `prompts/REPO_POLICIES.md` now opens with its
|
|
||||||
scope: what we download and install ourselves in scripts and Dockerfiles
|
|
||||||
(https://git.eeqj.de/sneak/prompts/issues/154). Distribution packages are
|
|
||||||
outside the rule, and updating and upgrading them is allowed. Both checklists
|
|
||||||
say the same.
|
|
||||||
- 2026-11-04: Each repository now commits yarn 4 and installs with
|
|
||||||
`yarn install --immutable` (https://git.eeqj.de/sneak/prompts/issues/149), on
|
|
||||||
sneak's ruling at
|
|
||||||
https://git.eeqj.de/sneak/prompts/issues/149#issuecomment-167558. Product
|
|
||||||
repositories convert when they next have work. These changed:
|
|
||||||
- This repository carries `.yarn/releases/yarn-4.18.1.cjs`, and its
|
|
||||||
`yarn.lock` is in yarn 4's format.
|
|
||||||
- `script/bootstrap` no longer stops on yarn's major version.
|
|
||||||
- Node comes from the distribution's newest Node package, which on Alpine
|
|
||||||
3.24 is `nodejs-current`.
|
|
||||||
- A `Dockerfile` stage that needs yarn also copies `.yarnrc.yml` and
|
|
||||||
`.yarn/releases/`, and may start from any distribution that packages node
|
|
||||||
and yarn.
|
|
||||||
- Both checklists give the steps, and the ignore files keep yarn's install
|
|
||||||
state out of git and the build context.
|
|
||||||
- 2026-11-04: An agent whose work is confined to one package may run `go test`
|
|
||||||
directly on that package's suite, or on individual tests in it, while
|
|
||||||
iterating (https://git.eeqj.de/sneak/prompts/issues/51), on sneak's ruling at
|
|
||||||
https://git.eeqj.de/sneak/prompts/issues/51#issuecomment-167600. The full
|
|
||||||
`make check` is still required before every push, and the `Makefile` gains
|
|
||||||
nothing. The rule on Docker now names the lint and test gates, because a run
|
|
||||||
while iterating is not one.
|
|
||||||
- 2026-11-04: node, yarn, npm, python, pip and venv now come from the
|
|
||||||
distribution with no version and no hash
|
|
||||||
(https://git.eeqj.de/sneak/prompts/issues/146), on sneak's ruling at
|
|
||||||
https://git.eeqj.de/sneak/prompts/issues/146#issuecomment-166033. Third-party
|
|
||||||
packages stay pinned by hash. These changed:
|
|
||||||
- `script/bootstrap` no longer uses nvm or corepack, and stops when yarn's
|
|
||||||
major version is not 1.
|
|
||||||
- `script/bootstrap` installs node, yarn and the node packages only when
|
|
||||||
`yarn.lock` is in the tree.
|
|
||||||
- `script/bootstrap`, `script/fmt` and `script/fmt-check` run `yarn` or
|
|
||||||
`yarnpkg`, whichever is present.
|
|
||||||
- This repository's `Dockerfile` starts from Alpine 3.24.
|
|
||||||
- The Python `test` phase example starts from `debian:trixie-slim`.
|
|
||||||
- A Python repository's `script/bootstrap` creates its virtual environment
|
|
||||||
at `$HOME/.pipenv`, so it works on a host and in a `Dockerfile`.
|
|
||||||
- `PIP_ONLY_BINARY=:all:` stops a package with no wheel, so pip downloads no
|
|
||||||
build tools without a hash check.
|
|
||||||
- 2026-11-04: Rewrote `prompts/REPO_POLICIES.md` sentence by sentence
|
|
||||||
(https://git.eeqj.de/sneak/prompts/issues/136), on sneak's yes at
|
|
||||||
https://git.eeqj.de/sneak/prompts/issues/136#issuecomment-165193. Every rule
|
|
||||||
keeps its meaning and its place, and `must` and `should` stay as they were.
|
|
||||||
Long sentences are split, comma-chained lists are now bulleted lists, and
|
|
||||||
every reason stays. Code blocks, digests, URLs, file names, commands and
|
|
||||||
quoted strings are unchanged.
|
|
||||||
- 2026-11-03: The canonical golangci-lint is now v2.15.0, still built with
|
|
||||||
go1.27.0, so the `go` directive rule is unchanged (issue 142). Repositories
|
|
||||||
pick this up on their next re-vendor. Each item in the canonical
|
|
||||||
`.golangci.yml` was tried on a scratch module. These changed:
|
|
||||||
- `canonicalheader` is enabled again, because v2.15.0 fixes the random
|
|
||||||
misses behind issue 105.
|
|
||||||
- The `depguard` exemption covers only the files directly inside a directory
|
|
||||||
whose name ends in `test`. It used to reach every directory below that one
|
|
||||||
too. The name of the directory a repository is cloned into no longer
|
|
||||||
counts.
|
|
||||||
- `gomodguard_v2` also blocks `github.com/go-redis/redis/v9`, whose
|
|
||||||
pre-releases can still be imported under that path.
|
|
||||||
- `uniq-by-line` is now `false`, so a line that trips two linters reports
|
|
||||||
both findings.
|
|
||||||
- Three comments are corrected:
|
|
||||||
- `exhaustruct` is listed as deprecated.
|
|
||||||
- The test double is named `github.com/go-redis/redismock/v9`.
|
|
||||||
- The claim that every blocked module is in the Go package defaults is
|
|
||||||
gone.
|
|
||||||
- A comment says the file has no `formatters` section, so
|
|
||||||
`golangci-lint run` does not run `gofmt`.
|
|
||||||
- 2026-11-03: A package from the distribution's own package index now needs no
|
|
||||||
version and no hash, and pulling that index is allowed
|
|
||||||
(https://git.eeqj.de/sneak/prompts/issues/72), on sneak's answer at
|
|
||||||
https://git.eeqj.de/sneak/prompts/issues/72#issuecomment-165196. The
|
|
||||||
distribution is the pinned base image's in a `Dockerfile` and the host's on a
|
|
||||||
host. It is trusted, and everything else stays pinned by hash. A package
|
|
||||||
source that a `Dockerfile` adds itself does not get the exception. The pinning
|
|
||||||
rule of `REPO_POLICIES.md` and both checklists say so, and the canonical Go
|
|
||||||
`Dockerfile`'s `apk add` line has a comment saying why it is allowed.
|
|
||||||
- 2026-11-03: A first test run that timed out now gets no verbose rerun
|
|
||||||
(https://git.eeqj.de/sneak/prompts/issues/61), on sneak's approval at
|
|
||||||
https://git.eeqj.de/sneak/prompts/issues/61#issuecomment-165195. The Go recipe
|
|
||||||
in `REPO_POLICIES.md` looks in the first run's output for
|
|
||||||
`panic: test timed out` or `*** Test killed`, and exits 1 when either is
|
|
||||||
there. The Python `make test` example takes the same `timeout 90 sh -c`
|
|
||||||
wrapper as its `Dockerfile` example. The 60 and 90 second rule and the
|
|
||||||
5-minute rule now say a hung package uses the backstop once. The Go item in
|
|
||||||
both repo checklists now asks for this, so a repository with the old recipe
|
|
||||||
fails it.
|
|
||||||
- 2026-10-27: Added `prompts/API_POLICIES.md`
|
|
||||||
(https://git.eeqj.de/sneak/prompts/issues/137). It holds sneak's rule from
|
|
||||||
https://git.eeqj.de/sneak/routewatch/issues/199 that a value in an API
|
|
||||||
response is never a string with a label or unit in it. `REPO_POLICIES.md` and
|
|
||||||
the code style commands in the README name the new file.
|
|
||||||
- 2026-10-21: Check builds may now also keep the Python packages a `test` phase
|
|
||||||
installs from `Pipfile.lock` (issue 133), on sneak's ruling in
|
|
||||||
https://git.eeqj.de/sneak/rfscan/issues/80#issuecomment-153437. The install
|
|
||||||
comes before `ARG CACHEBUST`: `COPY script/ script/`,
|
|
||||||
`COPY Pipfile Pipfile.lock ./`, then `RUN script/bootstrap`. In that step
|
|
||||||
`script/bootstrap` installs nothing beyond system packages, pipenv and its
|
|
||||||
dependencies by hash, and the packages from the lockfile. It installs no
|
|
||||||
Python, because the tests use the base image's. `--deploy` installs only what
|
|
||||||
the lockfile names, checks every package against its hashes, and fails when
|
|
||||||
the lockfile is out of date with `Pipfile`. A kept layer holds nothing a new
|
|
||||||
install would refuse. A package built from source and the system packages may
|
|
||||||
differ in a new install. As with Go's modules, the packages are kept in a
|
|
||||||
layer, not a cache mount. The tests still run after `ARG CACHEBUST`, and every
|
|
||||||
other stage still installs its Python packages after it. `REPO_POLICIES.md`
|
|
||||||
gains a short Python `test` phase example, and both checklists and the README
|
|
||||||
state the rule the same way. rfscan picks this up on its next re-vendor.
|
|
||||||
- 2026-10-21: The canonical `.golangci.yml` now accepts a local `replace` of
|
|
||||||
`github.com/grafana/sobek` in a repository's root `go.mod` (issue 134), for
|
|
||||||
homoicon, which keeps a local copy of sobek on sneak's decision in
|
|
||||||
https://git.eeqj.de/sneak/homoicon/issues/1759#issuecomment-153261. Every
|
|
||||||
other local `replace` is still refused. It is an exclusion rather than a
|
|
||||||
`replace-allow-list` entry because gomoddirectives does not check that list
|
|
||||||
for a `replace` that points at a local path. homoicon picks this up on its
|
|
||||||
next re-vendor.
|
|
||||||
- 2026-10-18: Check builds may now also keep Go's downloaded modules,
|
|
||||||
golangci-lint's cache and the layers that install system packages (issue 130),
|
|
||||||
on sneak's ruling there. In each stage of the canonical Go `Dockerfile`, the
|
|
||||||
system-package install and the module download (`COPY go.mod go.sum ./`,
|
|
||||||
`RUN go mod download`) come before `ARG CACHEBUST`, so Docker keeps them until
|
|
||||||
the base image, the install line, `go.mod` or `go.sum` changes. The modules
|
|
||||||
are kept as a layer, not a cache mount, because Go does not check the files in
|
|
||||||
a cache mount again. `golangci-lint run` also mounts golangci-lint's cache,
|
|
||||||
`/root/.cache/golangci-lint`. Every step that lints, tests or compiles still
|
|
||||||
comes after `ARG CACHEBUST` and runs on every check build, and both `go test`
|
|
||||||
runs keep `-count=1`. `REPO_POLICIES.md`, both checklists, the Go style guide,
|
|
||||||
the README and the script comments state the rule the same way. This repo's
|
|
||||||
own `Dockerfile` is unchanged: its `script/bootstrap` step also installs node
|
|
||||||
packages, which the ruling does not cover. Repositories pick this up on their
|
|
||||||
next re-vendor.
|
|
||||||
- 2026-10-15: Check builds now keep Go's build cache between runs (issue 113),
|
|
||||||
on sneak's ruling there that Go's compile cache may survive. `script/lint`,
|
|
||||||
`script/test`, `script/cibuild` and `script/docker` pass a new `CACHEBUST`
|
|
||||||
build argument on every build in place of `--no-cache`, which also emptied the
|
|
||||||
cache mounts. Every `Dockerfile` stage declares `ARG CACHEBUST` first, so
|
|
||||||
every `RUN` step still runs on every check build. The canonical Go
|
|
||||||
`Dockerfile` mounts Go's build cache on the steps that compile and runs both
|
|
||||||
`go test` runs with `-count=1`, so no test result is reused. A stage without
|
|
||||||
the `ARG` line is served from cache, so repositories re-vendor the scripts and
|
|
||||||
the `ARG` lines in one commit. Not yet tried on the shared runner.
|
|
||||||
- 2026-10-08: The canonical `script/bootstrap` now uses the installed node only
|
|
||||||
when its major version is the pinned one (issue 118). Otherwise, as when node
|
|
||||||
is missing, it installs the pinned node under nvm and installs yarn and the
|
|
||||||
packages under it. It prints the version of the node it uses either way. The
|
|
||||||
CI runner image ships node 24, under which the pinned yarn 1.22.22 printed the
|
|
||||||
deprecation warning DEP0169 on every bootstrap. Only the major is compared
|
|
||||||
because the `Dockerfile` stages start from a node 22 alpine image whose exact
|
|
||||||
version is not the pin, and nvm cannot install a prebuilt node on alpine; the
|
|
||||||
version-comparison rule in `REPO_POLICIES.md` names node as its exception.
|
|
||||||
`script/fmt` and `script/fmt-check` pick their yarn with the same test: the
|
|
||||||
`yarn` on `PATH` when the installed node is the pinned major, and otherwise
|
|
||||||
yarn under the pinned node through nvm. `REPO_POLICIES.md` and both checklists
|
|
||||||
say so, and the checklists' final `script/cibuild` check names what the CI
|
|
||||||
runner image has: node 24 and no yarn. Not yet tried on the shared runner.
|
|
||||||
Repositories pick this up on their next re-vendor.
|
|
||||||
- 2026-10-07: The `script/cibuild` item in `NEW_REPO_CHECKLIST.md` now matches
|
|
||||||
the canonical `script/cibuild` (issue 125). Its image build carries the tag,
|
|
||||||
`-t "$tag"`, and the item says that `$version` comes from
|
|
||||||
`git describe --tags --always --dirty` (`unknown` if empty) and `$tag` from
|
|
||||||
`script/projectname`, each assigned on its own line before the build. A
|
|
||||||
repository written from the checklist got an untagged build, which leaves a
|
|
||||||
dangling image behind on every run, and was never told where `$version` comes
|
|
||||||
from. The other `docker build` commands the checklists and `REPO_POLICIES.md`
|
|
||||||
give for `script/` already matched their scripts.
|
|
||||||
- 2026-10-07: `script/lint` and `script/test` now build with
|
|
||||||
`--output type=cacheonly` in place of a tag (issue 123), so they still run
|
|
||||||
their phase uncached and fail on a failing step but write no image. Nothing
|
|
||||||
used those images, and writing one out cost about 16 seconds of a Go
|
|
||||||
repository's test build. `script/cibuild` and `script/docker` keep their tags.
|
|
||||||
`REPO_POLICIES.md`, both checklists and the README no longer say the gate
|
|
||||||
builds are tagged. Not yet tried on the shared runner. Repositories pick this
|
|
||||||
up on their next re-vendor.
|
|
||||||
- 2026-10-07: The canonical `.gitea/workflows/check.yml` now sets
|
|
||||||
`timeout-minutes: 20` on its `check` job (issue 120), so a hung build frees
|
|
||||||
the shared runner instead of holding it until the runner's own limit.
|
|
||||||
`script/cibuild` runs three Docker builds, each held to the 5-minute Docker
|
|
||||||
build limit, plus the bootstrap; if that limit changes (issue 113), the value
|
|
||||||
follows it. `REPO_POLICIES.md` and both checklists name the limit among what
|
|
||||||
the workflow sets. Not yet tried on the shared runner. Repositories pick this
|
|
||||||
up on their next re-vendor.
|
|
||||||
- 2026-10-07: The canonical `package.json` now has `"private": true` in place of
|
|
||||||
`"license": "MIT"` (issue 119), so a repository that copies it no longer
|
|
||||||
declares MIT whatever its own licence is. yarn does not print "No license
|
|
||||||
field" for a private package. This repository's own licence is unchanged.
|
|
||||||
- 2026-10-06: The canonical `.gitea/workflows/check.yml` now sets
|
|
||||||
`fetch-depth: 0` on its checkout step (issue 110), so CI fetches the history
|
|
||||||
and tags that `git describe --tags --always` needs, and a tagged repository
|
|
||||||
stamps the same version in CI as in a local build. `REPO_POLICIES.md` and both
|
|
||||||
checklists name `fetch-depth: 0` among what the workflow does, next to
|
|
||||||
`persist-credentials: false` and the `concurrency` block, instead of asking
|
|
||||||
each tagged repository to add it. Not yet tried on the shared runner, which is
|
|
||||||
out of disk space. Repositories pick this up on their next re-vendor.
|
|
||||||
- 2026-10-06: The canonical `script/bootstrap` now runs `apt-get update` once,
|
|
||||||
before the first `apt-get install` of a run (issue 115). The Gitea runner
|
|
||||||
image starts with empty package lists, so installing anything it lacks, such
|
|
||||||
as Go, failed with `Unable to locate package`. A repository's own section no
|
|
||||||
longer needs a refresh of its own; `sneak/bsfirehose` and `sneak/dnswatcher`
|
|
||||||
drop theirs at their next re-vendor.
|
|
||||||
- 2026-10-06: `REPO_POLICIES.md` and both checklists now say that a checkout
|
|
||||||
whose `.git` is a file, a linked worktree or a repository checked out as a
|
|
||||||
submodule, is the exception to a plain `docker build .` succeeding (issue
|
|
||||||
111): that file points to a git directory outside the build context, so the
|
|
||||||
build cannot read the version and the version check in the canonical
|
|
||||||
`Dockerfile` stops it. Such a build is given its version with
|
|
||||||
`--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already do.
|
|
||||||
The check itself is unchanged.
|
|
||||||
- 2026-10-06: The canonical `.gitea/workflows/check.yml` now has a `concurrency`
|
|
||||||
block, so a new push cancels the older run on the same branch and no other,
|
|
||||||
and its checkout step sets `persist-credentials: false`, so the job's token is
|
|
||||||
not left in `.git/config` (issue 107). `REPO_POLICIES.md` and both checklists
|
|
||||||
describe the workflow as it now is. Not yet tried on the shared runner, which
|
|
||||||
is out of disk space. Repositories pick this up on their next re-vendor.
|
|
||||||
- 2026-10-06: The canonical `.golangci.yml` now disables `canonicalheader`
|
|
||||||
(issue 105). In golangci-lint v2.14.0 it misses findings at random in a
|
|
||||||
package that also calls `ResponseWriter.Header()`, so the same tree can fail
|
|
||||||
lint on one run and pass on the next. It comes back once a pinned
|
|
||||||
golangci-lint release fixes it.
|
|
||||||
- 2026-10-06: The canonical `.gitignore` and `.editorconfig` now each end with a
|
|
||||||
comment saying the repository's own entries go below it and a re-vendor keeps
|
|
||||||
them (issue 103, which took in issue 104), as `.dockerignore`'s header already
|
|
||||||
does. `.editorconfig` gains a `[*.go]` section with tabs, since `gofmt`
|
|
||||||
decides Go indentation everywhere. `REPO_POLICIES.md` and both checklists say
|
|
||||||
that each of these two files is the canonical content followed by the
|
|
||||||
repository's own entries, which a re-vendor keeps, and the Go styleguide puts
|
|
||||||
`*.log`, `*.out`, `*.test` and binaries among those entries. Common outputs
|
|
||||||
stay out of the canonical `.gitignore`; each repository lists its own.
|
|
||||||
- 2026-10-05: `script/cibuild`, `script/docker`, `script/lint` and `script/test`
|
|
||||||
now assign the image tag from `script/projectname` on its own line before the
|
|
||||||
`docker build` (issue 101), so `set -e` stops the script where
|
|
||||||
`script/projectname` fails instead of running `docker build` with a broken
|
|
||||||
tag. The comment above it in each script says why, and the snippets in
|
|
||||||
`REPO_POLICIES.md` show the same form. Repositories pick this up on their next
|
|
||||||
re-vendor.
|
|
||||||
- 2026-10-04: Went through the fleet findings recorded on 2026-08-09 (issue 62)
|
|
||||||
and added the two rules `REPO_POLICIES.md` did not yet state: a new or changed
|
|
||||||
check is proven by planting a defect it must catch; and a change to a separate
|
|
||||||
workflow limited to `main` is first run from the feature branch, added to that
|
|
||||||
workflow's `branches` list and removed again before merging. The other
|
|
||||||
findings were already stated, replaced by `--no-cache`, about git worktrees,
|
|
||||||
or about how agents work together. The warning against
|
|
||||||
`golangci-lint config verify` is dropped because sneak ruled on
|
|
||||||
https://git.eeqj.de/sneak/prompts/issues/40 (2026-08-10) that there is no
|
|
||||||
config check step and the config is assumed valid; a vendored `.golangci.yml`
|
|
||||||
stays byte-identical to the canonical copy. The issue gives each reason.
|
|
||||||
- 2026-10-04: `REPO_POLICIES.md` now says which `Dockerfile` stages run
|
|
||||||
`script/bootstrap` (issue 90). The gate phases and the build stage start from
|
|
||||||
their pinned base images and install what those images lack either inline, as
|
|
||||||
the canonical Go `Dockerfile` does for `git`, or by running
|
|
||||||
`script/bootstrap`, as this repo's own `Dockerfile` does for its yarn
|
|
||||||
packages. The development environment stage, the final stage of a non-server
|
|
||||||
repo, runs `script/bootstrap`. The new repo checklist says the same.
|
|
||||||
- 2026-10-04: Added a root `.gitattributes` that merges `TODO.md` with git's
|
|
||||||
union merge (issue 98), so two branches that each add an entry at the top of
|
|
||||||
Completed Steps merge without a conflict. Git now never reports a conflict in
|
|
||||||
`TODO.md`: a real conflict elsewhere keeps both versions of the line, and when
|
|
||||||
two new entries share an identical line, one is inserted into the middle of
|
|
||||||
the other, which a rebase can do to an entry already on `next`. Read the
|
|
||||||
merged entries after every merge or rebase. This applies to this repository
|
|
||||||
only; no canonical file changed.
|
|
||||||
- 2026-10-04: The canonical `.dockerignore` now also keeps out the git `config`
|
|
||||||
of a submodule that keeps its own `.git` directory, which still reached the
|
|
||||||
image (issue 88): both git patterns now carry the `**/` prefix. A submodule
|
|
||||||
whose name has a `config` segment (`config`, `deploy/config`, `config/lib`)
|
|
||||||
still loses its whole git directory, so Go's version stamping fails the build;
|
|
||||||
the file records this as a `KNOWN GAP:` with the remedy,
|
|
||||||
`git submodule add --name`. Closing it would take a wildcard re-include, which
|
|
||||||
makes BuildKit walk every excluded directory, such as `node_modules`, on every
|
|
||||||
build. `REPO_POLICIES.md` and both checklists say so in the same words.
|
|
||||||
- 2026-10-04: The note under the canonical Go `Dockerfile` example in
|
|
||||||
`REPO_POLICIES.md` now installs lint-phase system libraries with `apt-get`
|
|
||||||
under their Debian package names (issue 83). The `golangci/golangci-lint`
|
|
||||||
image is Debian-based and has no `apk`, so the old `apk add` instruction
|
|
||||||
failed as written. Nothing is pinned or unpinned; that is still open on
|
|
||||||
issue 72.
|
|
||||||
- 2026-10-04: Fixed the server lifecycle example in
|
|
||||||
`prompts/GO_HTTP_SERVER_CONVENTIONS.md` (issue 86). Only fx handles SIGINT and
|
|
||||||
SIGTERM, and `Run()` in `main` exits with the shutdown's exit code. A listen
|
|
||||||
error asks fx to shut down with exit code 1 through `fx.Shutdowner`; a Sentry
|
|
||||||
start failure is returned from the server's start hook instead of calling
|
|
||||||
`os.Exit` from a goroutine, so the stop hooks of what had started still run.
|
|
||||||
The server's stop hook shuts the HTTP server down within 5 seconds and fails
|
|
||||||
when requests are still running. A new paragraph says who owns signals and the
|
|
||||||
exit code.
|
|
||||||
- 2026-10-04: `REPO_POLICIES.md` now says how a Go tool a repo needs on the host
|
|
||||||
is pinned (issue 37): installed with `go install` pinned to a commit hash,
|
|
||||||
never tracked as a `go.mod` tool dependency or through a `tools.go` file.
|
|
||||||
golangci-lint is unaffected, since no repo installs it on the host.
|
|
||||||
- 2026-10-04: The canonical `.gitignore` and `.dockerignore` now also keep out
|
|
||||||
`id_ecdsa_sk` and `id_ed25519_sk`, the private key files `ssh-keygen` writes
|
|
||||||
for keys backed by a hardware security key (issue 81). Their `.pub` halves
|
|
||||||
stay trackable.
|
|
||||||
- 2026-10-04: `package.json` now has `"license": "MIT"`, matching `LICENSE`, so
|
|
||||||
yarn no longer prints "No license field" when `script/bootstrap` runs it
|
|
||||||
inside the Docker phases (issue 76). That was the only yarn warning there.
|
|
||||||
- 2026-10-04: `REPO_POLICIES.md` now states that guidance for coding agents
|
|
||||||
lives in one `AGENTS.md` at the repository root, never under a file or
|
|
||||||
directory named after one agent tool and never in separate memory files (issue
|
|
||||||
31). This retires the rule, still present in older vendored copies, that kept
|
|
||||||
agent memory as committed files under `.claude/memory/`. `AGENTS.md` joins the
|
|
||||||
list of files allowed in the root, and both checklists say so.
|
|
||||||
- 2026-10-04: Rewrote the note under the canonical Go `make test` example in
|
|
||||||
`REPO_POLICIES.md` (issue 77), which still named the cache-busting build
|
|
||||||
argument that `--no-cache` replaced. It now says where Go's test result cache
|
|
||||||
can replay a pass: on a developer's machine, where the Makefile target runs,
|
|
||||||
and not in the `test` phase of the `Dockerfile`, whose base image and earlier
|
|
||||||
steps hold no result for the repo's tests.
|
|
||||||
- 2026-10-04: The Makefile examples in the Go styleguide and the HTTP server
|
|
||||||
conventions now fall back to `dev` when `git describe` prints nothing (outside
|
|
||||||
a git checkout, or where git is missing or refuses the checkout), instead of
|
|
||||||
stamping an empty version (issue 74). The canonical `Dockerfile` already fails
|
|
||||||
on a `dev` version when `.git` is in the build context.
|
|
||||||
- 2026-10-04: The canonical `.dockerignore` now also keeps out each submodule's
|
|
||||||
`config` (issue 75). A submodule's git directory lives under `.git/modules/`,
|
|
||||||
nested again for its own submodules, and its `config` can hold a credential
|
|
||||||
just like `.git/config`. The pattern `.git/modules/**/config` covers every
|
|
||||||
depth and leaves the top-level `.git` that `git describe` reads untouched.
|
|
||||||
`REPO_POLICIES.md` and both checklists say so in the same words.
|
|
||||||
- 2026-10-03: Fixed two defects in the canonical Go `Dockerfile` example (issue
|
|
||||||
73). The test phase now uses the Debian Go image, since `-race` needs cgo and
|
|
||||||
the alpine image has no C compiler, so the phase failed before running a test.
|
|
||||||
The stage that compiles runs `git config --system --add safe.directory /src`,
|
|
||||||
because a context sent as a tar stream keeps the sender's file owners and git
|
|
||||||
refuses that checkout, leaving the version empty. Both checklists state that
|
|
||||||
step in the same words.
|
|
||||||
- 2026-10-03: Moved the canonical golangci-lint to v2.14.0, built with go1.27,
|
|
||||||
because v2.12.2 refuses to lint a module whose `go` directive is 1.27 (issue
|
|
||||||
65). Releases from v2.13.0 deprecate `exhaustruct` in favour of
|
|
||||||
`exhaustruct_v5`, which `default: all` switches on, so the canonical
|
|
||||||
`.golangci.yml` now disables `exhaustruct_v5` beside `exhaustruct`. v2.12.2
|
|
||||||
rejects that file, so `REPO_POLICIES.md` and both repo checklists now say a
|
|
||||||
repo sets the lint phase digest and re-vendors `.golangci.yml` in one commit.
|
|
||||||
- 2026-10-03: Brought the canonical `.gitignore` level with `.dockerignore` on
|
|
||||||
secrets (issue 38): it now also ignores `prod.env`-style `*.env` files,
|
|
||||||
`.envrc`, `*.p12`, `*.pfx` and the extensionless SSH private keys, written to
|
|
||||||
`.gitignore`'s own rules (no `**/` prefix) and case-folded with character
|
|
||||||
ranges. `example.env` and `sample.env` stay trackable through negations.
|
|
||||||
- 2026-10-02: The image version now comes from git inside the build (issues 69
|
|
||||||
and 71), superseding the 2026-09-08 entry that excluded `.git`. The canonical
|
|
||||||
`.dockerignore` sends `.git` but keeps out `.git/config`, which can hold a
|
|
||||||
credential. The Dockerfile example in `REPO_POLICIES.md` installs `git`, takes
|
|
||||||
the `VERSION` build argument when one is given and otherwise
|
|
||||||
`git describe --tags --always`, and fails when `.git` exists but the version
|
|
||||||
is empty, `dev` or `unknown`; a plain `docker build .` with no build arguments
|
|
||||||
must succeed. This repo's `script/docker` and `script/cibuild` still pass
|
|
||||||
`--build-arg VERSION`, since its own `Dockerfile` compiles nothing.
|
|
||||||
- 2026-09-08: Moved linting and testing into Docker as phases of the main
|
|
||||||
`Dockerfile`, per the owner ruling on issue 40. `script/lint` and
|
|
||||||
`script/test` build one phase each by name with `--no-cache` — the same answer
|
|
||||||
issue 26 got, so no separate cache-busting mechanism survives — and the final
|
|
||||||
stage copies a harmless file from both, so the image cannot be built unless
|
|
||||||
they pass. This also closes issue 30: a container has its own result cache and
|
|
||||||
its own lock, so a lint verdict can no longer belong to another checkout. No
|
|
||||||
separate lint Dockerfile, and no `golangci-lint config verify` step.
|
|
||||||
`script/check` runs the gates and nothing else, and `script/cibuild`
|
|
||||||
bootstraps first, since it is all CI runs and `script/fmt-check` is native.
|
|
||||||
- 2026-09-08: Kept in-repo agent scratch out of the Docker build context and out
|
|
||||||
of version control: `.claude/` is one full checkout of the repo per in-flight
|
|
||||||
agent, and under `COPY . .` all of it was reaching the image. Also closed the
|
|
||||||
consequence of excluding `.git` — `git describe` yields an empty version
|
|
||||||
inside a build stage without failing, so `script/docker` and `script/cibuild`
|
|
||||||
now compute the version on the host and pass `--build-arg VERSION`.
|
|
||||||
- 2026-09-08: Closed the secret exposure in the canonical `.dockerignore`: a
|
|
||||||
local `.env`, `*.pem` or `*.key` was reaching the build context under
|
|
||||||
`COPY . .`, invisible to every git-based check. The patterns are now written
|
|
||||||
to `.dockerignore`'s own semantics — `**/`-prefixed so they hold at every
|
|
||||||
depth, case-folded with character ranges — and `REPO_POLICIES.md` requires
|
|
||||||
verifying by enumerating the image rather than by reading the file.
|
|
||||||
- 2026-09-08: Made a pinned tool in `script/bootstrap` actually reach the host.
|
|
||||||
`REPO_POLICIES.md` now requires comparing the installed version against the
|
|
||||||
pin rather than testing `PATH` presence, and re-resolving the binary through
|
|
||||||
`PATH` after installing, so a version bump cannot be a silent no-op and a
|
|
||||||
shadowed install cannot report success.
|
|
||||||
- 2026-09-08: Closed the false green in the canonical CI gate: `script/cibuild`
|
|
||||||
and `script/docker` now build with `--no-cache`, so the Dockerfile's check
|
|
||||||
layers cannot be served from cache on an unchanged tree, and the text claiming
|
|
||||||
a bare `docker build .` proves the checks ran is corrected in
|
|
||||||
`REPO_POLICIES.md`, both checklists and the Go styleguide.
|
|
||||||
- 2026-09-03: Added `-count=1` to both `go test` invocations in the canonical Go
|
|
||||||
`make test` example in `REPO_POLICIES.md`, so the target cannot report a
|
|
||||||
cached pass it did not earn, and documented that Go's test-result cache is a
|
|
||||||
second, independent cache stacked below the Docker layer cache.
|
|
||||||
- 2026-08-31: Migrated the canonical `.golangci.yml` from the deprecated
|
|
||||||
`gomodguard` to `gomodguard_v2`: the old linter is disabled by name (which is
|
|
||||||
what silences the deprecation warning), the successor is named explicitly in
|
|
||||||
`linters.enable`, and it carries a `blocked` module list drawn only from
|
|
||||||
decisions already recorded in the Go package defaults.
|
|
||||||
- 2026-08-07: Set the canonical `.golangci.yml` to the org-standard v2-schema
|
|
||||||
config already deployed byte-identical across the org's Go repos (settings
|
|
||||||
under `linters.settings` so thresholds like lll/funlen/cyclop/dupl actually
|
|
||||||
apply under golangci-lint v2). Recorded the canonical golangci-lint version
|
|
||||||
(v2.12.2, commit-pinned) in REPO_POLICIES.md.
|
|
||||||
- 2026-03-20: Strengthened constructor naming and Params struct rules in the Go
|
|
||||||
styleguide.
|
|
||||||
- 2026-03-18: Documented fail-fast Dockerfile lint stage and conditional -v test
|
|
||||||
rerun patterns in REPO_POLICIES.md.
|
|
||||||
- 2026-03-11: Added HTTP service hardening policy for 1.0 releases.
|
|
||||||
- 2026-03-10: Added policy: no build artifacts in repos.
|
|
||||||
- 2026-03-04: Added LLM prose tells reference and copyediting checklist, then
|
|
||||||
several self-applied revision passes.
|
|
||||||
- 2026-02-28: Expanded the pre-1.0 schema migration rule; added clawpub
|
|
||||||
reference.
|
|
||||||
- 2026-02-23: Added Go style rules (no type-only packages, Stringer for
|
|
||||||
string-based types); template repos section in README.
|
|
||||||
- 2026-02-22: Initial policy corpus: REPO_POLICIES.md, code styleguides
|
|
||||||
(general, Go, JS, Python), repo checklists, CI policy, hash pinning, Go HTTP
|
|
||||||
server conventions, repo scaffolding.
|
|
||||||
|
|
||||||
# Future Steps
|
# Future Steps
|
||||||
|
|
||||||
- Finish, format, and commit FIXUP_CLEAN.md and FIXUP_REPORT.md (the Next Step).
|
- Finish, format, and commit FIXUP_CLEAN.md and FIXUP_REPORT.md (the Next Step).
|
||||||
- Commit this TODO.md at the repo root; it is the last missing policy file.
|
|
||||||
- Decide the fate of untracked resume.sh: commit it or delete it.
|
- Decide the fate of untracked resume.sh: commit it or delete it.
|
||||||
- Add more prompt templates for common development tasks (from README TODO).
|
- Add more prompt templates for common development tasks (from README TODO).
|
||||||
+120
-10
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Code Styleguide — Go
|
title: Code Styleguide — Go
|
||||||
last_modified: 2026-11-07
|
last_modified: 2026-11-16
|
||||||
---
|
---
|
||||||
|
|
||||||
1. Format Go code with `gofmt` and then `golines -m 77`, through `make fmt`.
|
1. Format Go code with `gofmt` and then `golines -m 77`, through `make fmt`.
|
||||||
@@ -113,13 +113,7 @@ last_modified: 2026-11-07
|
|||||||
1. Write a `Dockerfile` for every repo, even if it only runs the tests and
|
1. Write a `Dockerfile` for every repo, even if it only runs the tests and
|
||||||
linting. It carries the lint and test phases, and the final stage depends on
|
linting. It carries the lint and test phases, and the final stage depends on
|
||||||
both, so a build makes sure the code is in an able-to-be-compiled state,
|
both, so a build makes sure the code is in an able-to-be-compiled state,
|
||||||
linted, and its tests run. Go through `script/cibuild` or `script/docker`
|
linted, and its tests run.
|
||||||
rather than a bare `docker build .`: they pass a new `CACHEBUST` value on
|
|
||||||
every build, which reruns every step that lints, tests or compiles and keeps
|
|
||||||
the system packages, Go's modules and build cache, and golangci-lint's
|
|
||||||
cache; `--no-cache` would throw all of them away. Without a new value an
|
|
||||||
unchanged tree serves the gate layers from cache and the build reports a
|
|
||||||
green it never ran.
|
|
||||||
|
|
||||||
1. Every repo must have a `Makefile`. See
|
1. Every repo must have a `Makefile`. See
|
||||||
[Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
|
[Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
|
||||||
@@ -176,7 +170,7 @@ last_modified: 2026-11-07
|
|||||||
them a bit long.
|
them a bit long.
|
||||||
|
|
||||||
1. Use descriptive names for modules and filenames. Avoid generic names like
|
1. Use descriptive names for modules and filenames. Avoid generic names like
|
||||||
`server`. `util` is banned.
|
`server`. The rules for package names are under Naming, below.
|
||||||
|
|
||||||
1. Constructors **must** take a `Params` struct (or `ThingParams` when
|
1. Constructors **must** take a `Params` struct (or `ThingParams` when
|
||||||
`NewThing()` is used), even for a single argument. Named fields in a Params
|
`NewThing()` is used), even for a single argument. Named fields in a Params
|
||||||
@@ -221,7 +215,7 @@ last_modified: 2026-11-07
|
|||||||
...
|
...
|
||||||
|
|
||||||
if err != nil {
|
if err != nil {
|
||||||
SendErrorResponse(w, MSGenericError)
|
SendErrorResponse(w, ErrBadRequest)
|
||||||
return
|
return
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -487,6 +481,122 @@ last_modified: 2026-11-07
|
|||||||
releasable". "Releasable" in this context means that it builds and functions
|
releasable". "Releasable" in this context means that it builds and functions
|
||||||
as expected, and that all tests and linting passes.
|
as expected, and that all tests and linting passes.
|
||||||
|
|
||||||
|
# Naming
|
||||||
|
|
||||||
|
Judge a name where it is read. A caller writes the package name, a dot and the
|
||||||
|
exported name, and reads them as one name: `http.Server`, `list.New`.
|
||||||
|
|
||||||
|
## Package names
|
||||||
|
|
||||||
|
1. Name a package for what it provides (`time`, `list`, `http`), because the
|
||||||
|
caller writes that name in front of everything the package exports.
|
||||||
|
|
||||||
|
1. Write a package name in lowercase letters and digits only, with its words
|
||||||
|
run together (`tabwriter`, never `tab_writer` or `tabWriter`), because that
|
||||||
|
is how the standard library spells every package name.
|
||||||
|
|
||||||
|
1. Never use a package name from the list below, or anything else that says
|
||||||
|
nothing about what is in it, because every program has a data model, helpers
|
||||||
|
and types.
|
||||||
|
- `model` and `models`
|
||||||
|
- `util` and `utils`
|
||||||
|
- `common`
|
||||||
|
- `misc`
|
||||||
|
- `helper` and `helpers`
|
||||||
|
- `types`
|
||||||
|
- `interfaces`
|
||||||
|
- `api`
|
||||||
|
|
||||||
|
1. Split a package whose code is about several things, so that each part can be
|
||||||
|
named for what it provides (`stringset`, not `util`).
|
||||||
|
|
||||||
|
1. Spell a word out unless its short form is the one everybody already uses
|
||||||
|
(`fmt`, `strconv`), because any other abbreviation has to be decoded.
|
||||||
|
|
||||||
|
1. Lengthen a package name that callers want for a variable or that a widely
|
||||||
|
used standard package has (`bufio`, not `buf`; `auditlog`, not `log`),
|
||||||
|
because importers must otherwise rename one of the two.
|
||||||
|
|
||||||
|
1. Give a package's directory the package's name, package `main` excepted, so
|
||||||
|
that the import path ends in the name the code uses.
|
||||||
|
|
||||||
|
1. Name a package that supports the tests of one package after that package
|
||||||
|
plus `test` (`storetest`, never `testutil` or `testhelper`), because the
|
||||||
|
name then says whose tests it is for.
|
||||||
|
|
||||||
|
1. Import a package under its own name unless two imports share a name or its
|
||||||
|
own name breaks these rules, so that a reader knows it without checking the
|
||||||
|
imports.
|
||||||
|
|
||||||
|
1. Give a renamed import the same local name in every file, so that one name
|
||||||
|
always means one package.
|
||||||
|
|
||||||
|
## Exported names
|
||||||
|
|
||||||
|
1. Never repeat the package name inside a longer exported name (`http.Server`,
|
||||||
|
not `http.HTTPServer`; `yamlconfig.Parse`, not
|
||||||
|
`yamlconfig.ParseYAMLConfig`), because the caller has already written it.
|
||||||
|
|
||||||
|
1. Use the same plain name in two packages when it fits both (`bufio.Reader`,
|
||||||
|
`csv.Reader`), because the package name already tells them apart.
|
||||||
|
|
||||||
|
1. Leave the receiver's type out of a method name, and the parameter and result
|
||||||
|
types out of a function name (`(c *Config) WriteTo(w)`, not
|
||||||
|
`WriteConfigTo`), because the signature already states them.
|
||||||
|
|
||||||
|
1. Put a type at the end of a function's name when the type is the only
|
||||||
|
difference between two functions (`ParseInt`, `ParseInt64`), because Go
|
||||||
|
needs a different name for each.
|
||||||
|
|
||||||
|
1. Use a noun for a function that only reports a value (`Owner()`,
|
||||||
|
`JobName(key)`), so that a call reads as the value it gives.
|
||||||
|
|
||||||
|
1. Use a verb for a function that does work, even when it also returns a result
|
||||||
|
(`Parse`, `WriteDetail(w)`), so that a call reads as the work it does.
|
||||||
|
|
||||||
|
1. Never start a getter with `Get` (`Owner()`, not `GetOwner()`; the setter is
|
||||||
|
`SetOwner()`), because the capital letter already tells the method from the
|
||||||
|
field.
|
||||||
|
|
||||||
|
1. Start a getter's name with `Fetch` when it reads the value from a database
|
||||||
|
or the network (`FetchOwner`, never `Owner` or `GetOwner`), because the
|
||||||
|
reader must know the call can be slow or fail.
|
||||||
|
|
||||||
|
1. Name a one-method interface for its method plus `er` (`Reader`,
|
||||||
|
`Formatter`), because the name then says the one thing a value of it does.
|
||||||
|
|
||||||
|
1. Use a well-known method's name and signature for a method that does the same
|
||||||
|
thing (`String()`, never `ToString()`), because readers and the standard
|
||||||
|
interfaces expect them.
|
||||||
|
|
||||||
|
1. Give another name to a method that differs in meaning or signature from a
|
||||||
|
well-known method of the same name (`Read`, `Write`, `Close`, `String`),
|
||||||
|
because readers rely on each name meaning one thing.
|
||||||
|
|
||||||
|
1. Write an initialism in one case throughout (`ServeHTTP`, `appID`, `URL` or
|
||||||
|
`url`; never `Url`, `Id` or `Http`), because that is how the standard
|
||||||
|
library spells them.
|
||||||
|
|
||||||
|
1. Write a constant in MixedCaps like every other name (`MaxPacketSize`, never
|
||||||
|
`MAX_PACKET_SIZE`), because an all-capitals name is exported whether or not
|
||||||
|
that was meant.
|
||||||
|
|
||||||
|
1. Name an error value `Err` plus what went wrong (`ErrNotFound`) and an error
|
||||||
|
type for what went wrong plus `Error` (`NotFoundError`), because callers
|
||||||
|
know a package's errors by those two forms.
|
||||||
|
|
||||||
|
## Local names
|
||||||
|
|
||||||
|
1. Match a local name's length to how far from its declaration it is used (`i`
|
||||||
|
in a short loop), because a reader far from the declaration has only the
|
||||||
|
name.
|
||||||
|
|
||||||
|
1. Name a receiver with one or two letters, never `this`, `self` or `me`,
|
||||||
|
because its role is plain from the method.
|
||||||
|
|
||||||
|
1. Use the same receiver name in every method of a type, so that the name
|
||||||
|
always means the receiver.
|
||||||
|
|
||||||
# Other Golang Tips and Best Practices (Optional)
|
# Other Golang Tips and Best Practices (Optional)
|
||||||
|
|
||||||
1. For any internet-facing http server, set appropriate timeouts and limits to
|
1. For any internet-facing http server, set appropriate timeouts and limits to
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Existing Repo Checklist
|
title: Existing Repo Checklist
|
||||||
last_modified: 2026-11-09
|
last_modified: 2026-11-16
|
||||||
---
|
---
|
||||||
|
|
||||||
Use this checklist when beginning work in a repo that may not yet conform to our
|
Use this checklist when beginning work in a repo that may not yet conform to our
|
||||||
@@ -49,23 +49,8 @@ with your task.
|
|||||||
`--target` names it, so a lost `COPY --from=` edge leaves `docker build .`
|
`--target` names it, so a lost `COPY --from=` edge leaves `docker build .`
|
||||||
passing while the gate never runs. Confirm by planting a violation, not by
|
passing while the gate never runs. Confirm by planting a violation, not by
|
||||||
reading the file.
|
reading the file.
|
||||||
- [ ] In every stage, 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. The `script/` builds pass a new `CACHEBUST` value on every build,
|
|
||||||
which reruns every `RUN` step after that line and leaves the layers above
|
|
||||||
it and the cache mounts in place; `--no-cache` would build those layers
|
|
||||||
again and empty the mounts. 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.
|
|
||||||
- [ ] Go: each Go stage downloads the modules (`COPY go.mod go.sum ./`,
|
- [ ] Go: each Go stage downloads the modules (`COPY go.mod go.sum ./`,
|
||||||
`RUN go mod download`) above `ARG CACHEBUST`; the steps that compile
|
`RUN go mod download`) before `COPY . .`; the steps that compile
|
||||||
(`golangci-lint run`, `go test`, `go build`) mount Go's build cache
|
(`golangci-lint run`, `go test`, `go build`) mount Go's build cache
|
||||||
(`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
|
(`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
|
||||||
also mounts golangci-lint's
|
also mounts golangci-lint's
|
||||||
@@ -74,7 +59,7 @@ with your task.
|
|||||||
that timed out gets no rerun, as in the canonical Go `Dockerfile` in
|
that timed out gets no rerun, as in the canonical Go `Dockerfile` in
|
||||||
`REPO_POLICIES.md`
|
`REPO_POLICIES.md`
|
||||||
- [ ] Python: a `test` phase that installs its packages from `Pipfile.lock` does
|
- [ ] Python: a `test` phase that installs its packages from `Pipfile.lock` does
|
||||||
it above `ARG CACHEBUST`, with `COPY script/ script/`,
|
it before `COPY . .`, with `COPY script/ script/`,
|
||||||
`COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
|
`COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
|
||||||
`script/bootstrap` runs in that step, it installs nothing beyond these:
|
`script/bootstrap` runs in that step, it installs nothing beyond these:
|
||||||
- system packages
|
- system packages
|
||||||
@@ -91,9 +76,8 @@ with your task.
|
|||||||
a package with no wheel for the image stops the install. In that step it
|
a package with no wheel for the image stops the install. In that step it
|
||||||
installs no Python, because a step above it already did. `Pipfile` names no
|
installs no Python, because a step above it already did. `Pipfile` names no
|
||||||
`python_version`, because `--deploy` stops when the distribution's Python
|
`python_version`, because `--deploy` stops when the distribution's Python
|
||||||
differs from it. The tests run after `ARG CACHEBUST`, and every other stage
|
differs from it. The tests run after `COPY . .`, as in the Python `test`
|
||||||
installs its Python packages after it, as in the Python `test` phase example
|
phase example in `REPO_POLICIES.md`
|
||||||
in `REPO_POLICIES.md`
|
|
||||||
|
|
||||||
- [ ] The gate phases invoke their tools directly, never through `make lint` or
|
- [ ] The gate phases invoke their tools directly, never through `make lint` or
|
||||||
`script/test` — those are themselves a `docker build` and would recurse
|
`script/test` — those are themselves a `docker build` and would recurse
|
||||||
@@ -223,23 +207,21 @@ with your task.
|
|||||||
- [ ] README has an **Entrypoints** section documenting the `script/`
|
- [ ] README has an **Entrypoints** section documenting the `script/`
|
||||||
entrypoints and linking the standard
|
entrypoints and linking the standard
|
||||||
- [ ] `script/lint` and `script/test` each run
|
- [ ] `script/lint` and `script/test` each run
|
||||||
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target <phase> --output type=cacheonly .`,
|
`docker build --target <phase> --output type=cacheonly .`, which builds
|
||||||
which builds their phase by name and writes no image, and no host
|
their phase by name and writes no image, and no host invocation anywhere
|
||||||
invocation anywhere in the repo can produce a lint verdict — grep for the
|
in the repo can produce a lint verdict — grep for the linter's own name
|
||||||
linter's own name across `script/`, the `Makefile` and CI config, not just
|
across `script/`, the `Makefile` and CI config, not just `script/lint`. A
|
||||||
`script/lint`. A second path is likeliest here: a `make lint-fast`, an
|
second path is likeliest here: a `make lint-fast`, an older
|
||||||
older host-versus-container branch, or a CI step calling the binary
|
host-versus-container branch, or a CI step calling the binary directly.
|
||||||
directly. `script/fmt` and `script/fmt-check` are expected hits and stay
|
`script/fmt` and `script/fmt-check` are expected hits and stay on the
|
||||||
on the host.
|
host.
|
||||||
- [ ] No `docker build` in `script/` leaves a dangling image behind:
|
- [ ] No `docker build` in `script/` leaves a dangling image behind:
|
||||||
`script/lint` and `script/test` write no image, and `script/docker` and
|
`script/lint` and `script/test` write no image, and `script/docker` and
|
||||||
`script/cibuild` tag theirs. A build that writes an untagged image leaves
|
`script/cibuild` tag theirs. A build that writes an untagged image leaves
|
||||||
one behind on every run, on every host and CI runner.
|
one behind on every run, on every host and CI runner.
|
||||||
- [ ] `script/cibuild` runs `script/bootstrap` before `script/check`, and builds
|
- [ ] `script/cibuild` runs `script/bootstrap` before `script/check`. Without
|
||||||
the image with a new `CACHEBUST` value on every build, like every
|
the bootstrap the CI run dies in `script/fmt-check`, which runs the
|
||||||
`docker build` in `script/`. Without the bootstrap the CI run dies in
|
formatter on the host and finds nothing installed.
|
||||||
`script/fmt-check`, which runs the formatter on the host and finds nothing
|
|
||||||
installed.
|
|
||||||
- [ ] `script/bootstrap` installs node, yarn and the node packages only when
|
- [ ] `script/bootstrap` installs node, yarn and the node packages only when
|
||||||
`yarn.lock` is in the tree. node and yarn come from the distribution when
|
`yarn.lock` is in the tree. node and yarn come from the distribution when
|
||||||
they are missing. It installs the node packages with
|
they are missing. It installs the node packages with
|
||||||
@@ -327,14 +309,7 @@ with your task.
|
|||||||
- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
|
- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
|
||||||
That host is the runner image
|
That host is the runner image
|
||||||
`docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
|
`docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
|
||||||
node 24. Take any yarn off `PATH` first. The run must show that the checks
|
node 24. Take any yarn off `PATH` first.
|
||||||
executed. A sub-second build means nothing ran. So does `CACHED` on a step
|
|
||||||
that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
|
|
||||||
that line, these steps are expected to show `CACHED`:
|
|
||||||
- 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 planted lint violation fails both `make lint` and a plain
|
- [ ] A planted lint violation fails both `make lint` and a plain
|
||||||
`docker build .`; revert it afterwards
|
`docker build .`; revert it afterwards
|
||||||
- [ ] Commit and merge fixes before starting your actual task
|
- [ ] Commit and merge fixes before starting your actual task
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: New Repo Checklist
|
title: New Repo Checklist
|
||||||
last_modified: 2026-11-09
|
last_modified: 2026-11-16
|
||||||
---
|
---
|
||||||
|
|
||||||
Use this checklist when creating a new repository from scratch. Follow the steps
|
Use this checklist when creating a new repository from scratch. Follow the steps
|
||||||
@@ -118,23 +118,8 @@ Template files can be fetched from:
|
|||||||
stage carries a `COPY --from=` of a harmless file from each so the image
|
stage carries a `COPY --from=` of a harmless file from each so the image
|
||||||
cannot be built unless both passed. Keep the final stage last: a stage
|
cannot be built unless both passed. Keep the final stage last: a stage
|
||||||
nothing depends on is built only when `--target` names it.
|
nothing depends on is built only when `--target` names it.
|
||||||
- In every stage, 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. The `script/` builds pass a new `CACHEBUST` value on every build,
|
|
||||||
which reruns every `RUN` step after that line and leaves the layers above
|
|
||||||
it and the cache mounts in place; `--no-cache` would build those layers
|
|
||||||
again and empty the mounts. A stage without the `ARG` line is served from
|
|
||||||
cache on an unchanged tree, so the scripts and every stage's
|
|
||||||
`ARG CACHEBUST` line are added in the same commit.
|
|
||||||
- Go: each Go stage downloads the modules (`COPY go.mod go.sum ./`,
|
- Go: each Go stage downloads the modules (`COPY go.mod go.sum ./`,
|
||||||
`RUN go mod download`) above `ARG CACHEBUST`; the steps that compile
|
`RUN go mod download`) before `COPY . .`; the steps that compile
|
||||||
(`golangci-lint run`, `go test`, `go build`) mount Go's build cache
|
(`golangci-lint run`, `go test`, `go build`) mount Go's build cache
|
||||||
(`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
|
(`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
|
||||||
also mounts golangci-lint's
|
also mounts golangci-lint's
|
||||||
@@ -143,7 +128,7 @@ Template files can be fetched from:
|
|||||||
that timed out gets no rerun, as in the canonical Go `Dockerfile` in
|
that timed out gets no rerun, as in the canonical Go `Dockerfile` in
|
||||||
`REPO_POLICIES.md`
|
`REPO_POLICIES.md`
|
||||||
- Python: a `test` phase that installs its packages from `Pipfile.lock` does
|
- Python: a `test` phase that installs its packages from `Pipfile.lock` does
|
||||||
it above `ARG CACHEBUST`, with `COPY script/ script/`,
|
it before `COPY . .`, with `COPY script/ script/`,
|
||||||
`COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
|
`COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
|
||||||
`script/bootstrap` runs in that step, it installs nothing beyond these:
|
`script/bootstrap` runs in that step, it installs nothing beyond these:
|
||||||
- system packages
|
- system packages
|
||||||
@@ -161,8 +146,7 @@ Template files can be fetched from:
|
|||||||
for the image stops the install. In that step it installs no Python,
|
for the image stops the install. In that step it installs no Python,
|
||||||
because a step above it already did. `Pipfile` names no
|
because a step above it already did. `Pipfile` names no
|
||||||
`python_version`, because `--deploy` stops when the distribution's
|
`python_version`, because `--deploy` stops when the distribution's
|
||||||
Python differs from it. The tests run after `ARG CACHEBUST`, and every
|
Python differs from it. The tests run after `COPY . .`, as in the Python
|
||||||
other stage installs its Python packages after it, as in the Python
|
|
||||||
`test` phase example in `REPO_POLICIES.md`
|
`test` phase example in `REPO_POLICIES.md`
|
||||||
|
|
||||||
- Server: the final stage builds and runs the application
|
- Server: the final stage builds and runs the application
|
||||||
@@ -227,13 +211,12 @@ are thin shims calling them. Model scripts:
|
|||||||
- [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
|
- [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
|
||||||
then `install-precommit`, plus repo-specific init
|
then `install-precommit`, plus repo-specific init
|
||||||
- [ ] `script/test` / `make test` —
|
- [ ] `script/test` / `make test` —
|
||||||
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target test --output type=cacheonly .`,
|
`docker build --target test --output type=cacheonly .`, which writes no
|
||||||
which writes no image; the phase runs real tests, not a no-op (90-second
|
image; the phase runs real tests, not a no-op (90-second timeout,
|
||||||
timeout, 60-second hard cap on wall time)
|
60-second hard cap on wall time)
|
||||||
- [ ] `script/lint` / `make lint` —
|
- [ ] `script/lint` / `make lint` —
|
||||||
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target lint --output type=cacheonly .`,
|
`docker build --target lint --output type=cacheonly .`, which writes no
|
||||||
which writes no image. No lint verdict may come from a host invocation of
|
image. No lint verdict may come from a host invocation of the linter.
|
||||||
the linter.
|
|
||||||
- [ ] `script/fmt` / `make fmt` — formats code (writes; native, never in a
|
- [ ] `script/fmt` / `make fmt` — formats code (writes; native, never in a
|
||||||
container). Go code gets `gofmt`, then `golines -m 77`.
|
container). Go code gets `gofmt`, then `golines -m 77`.
|
||||||
- [ ] `script/fmt-check` / `make fmt-check` — checks formatting (read-only;
|
- [ ] `script/fmt-check` / `make fmt-check` — checks formatting (read-only;
|
||||||
@@ -245,16 +228,15 @@ are thin shims calling them. Model scripts:
|
|||||||
- [ ] `script/projectname` — outputs the project name (used by `script/docker`
|
- [ ] `script/projectname` — outputs the project name (used by `script/docker`
|
||||||
for the image tag)
|
for the image tag)
|
||||||
- [ ] `script/docker` / `make docker` — builds Docker image, tagged via
|
- [ ] `script/docker` / `make docker` — builds Docker image, tagged via
|
||||||
`script/projectname` (byte-identical across repos); a new `CACHEBUST`
|
`script/projectname` (byte-identical across repos), with the version as a
|
||||||
value on every build, plus the version as a build arg
|
build arg
|
||||||
- [ ] `script/cibuild` — cd to repo root, run `script/bootstrap`, run
|
- [ ] `script/cibuild` — cd to repo root, run `script/bootstrap`, run
|
||||||
`script/check`, then
|
`script/check`, then
|
||||||
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t "$tag" .`
|
`docker build --build-arg VERSION="$version" -t "$tag" .` (what CI runs),
|
||||||
(what CI runs), with `$version` from
|
with `$version` from `git describe --tags --always --dirty` (`unknown` if
|
||||||
`git describe --tags --always --dirty` (`unknown` if empty) and `$tag`
|
empty) and `$tag` from `script/projectname`, each assigned on its own line
|
||||||
from `script/projectname`, each assigned on its own line before the build.
|
before the build. The bootstrap is required: CI checks out and runs this
|
||||||
The bootstrap is required: CI checks out and runs this alone, and
|
alone, and `script/fmt-check` runs the formatter on the host.
|
||||||
`script/fmt-check` runs the formatter on the host.
|
|
||||||
- [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by
|
- [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by
|
||||||
whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With
|
whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With
|
||||||
neither name on `PATH`, `script/fmt` and `script/fmt-check` print one line
|
neither name on `PATH`, `script/fmt` and `script/fmt-check` print one line
|
||||||
@@ -279,14 +261,7 @@ are thin shims calling them. Model scripts:
|
|||||||
- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
|
- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
|
||||||
That host is the runner image
|
That host is the runner image
|
||||||
`docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
|
`docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
|
||||||
node 24. Take any yarn off `PATH` first. The run must show that the checks
|
node 24. Take any yarn off `PATH` first.
|
||||||
executed. A sub-second build means nothing ran. So does `CACHED` on a step
|
|
||||||
that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
|
|
||||||
that line, these steps are expected to show `CACHED`:
|
|
||||||
- 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`
|
|
||||||
- [ ] Plant a lint violation and confirm both `make lint` and a plain
|
- [ ] Plant a lint violation and confirm both `make lint` and a plain
|
||||||
`docker build .` fail on it; revert. A plain build that passes proves the
|
`docker build .` fail on it; revert. A plain build that passes proves the
|
||||||
final stage is missing its `COPY --from=` edge to the gate phases.
|
final stage is missing its `COPY --from=` edge to the gate phases.
|
||||||
|
|||||||
+40
-110
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Repository Policies
|
title: Repository Policies
|
||||||
last_modified: 2026-11-09
|
last_modified: 2026-11-16
|
||||||
---
|
---
|
||||||
|
|
||||||
This document covers repository structure, tooling, and workflow standards. Code
|
This document covers repository structure, tooling, and workflow standards. Code
|
||||||
@@ -254,10 +254,8 @@ style conventions are in separate documents:
|
|||||||
phase and nothing else:
|
phase and nothing else:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
|
docker build --target lint --output type=cacheonly .
|
||||||
--target lint --output type=cacheonly .
|
docker build --target test --output type=cacheonly .
|
||||||
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
|
|
||||||
--target test --output type=cacheonly .
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**A stage that is not the last one in the file is built only when the final
|
**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
|
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
|
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
|
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`,
|
Inside a phase the tool is invoked directly: `golangci-lint`, `go test`,
|
||||||
`eslint`, `prettier`. The tool is never invoked through `make lint` or
|
`eslint`, `prettier`. The tool is never invoked through `make lint` or
|
||||||
@@ -298,55 +297,6 @@ style conventions are in separate documents:
|
|||||||
- the settings
|
- the settings
|
||||||
- the golangci-lint version
|
- 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:
|
|
||||||
- the base image
|
|
||||||
- their own lines
|
|
||||||
- the files they copy
|
|
||||||
|
|
||||||
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:
|
|
||||||
- plant a defect it must catch
|
|
||||||
- watch the run fail on it
|
|
||||||
- revert the defect
|
|
||||||
|
|
||||||
A green run alone shows neither that the check ran nor that it covers what
|
|
||||||
it should.
|
|
||||||
|
|
||||||
- **The gate phases are separate stages, and the build stage depends on both.**
|
- **The gate phases are separate stages, and the build stage depends on both.**
|
||||||
The lint phase is based on the `golangci/golangci-lint` image (pinned by
|
The lint phase is based on the `golangci/golangci-lint` image (pinned by
|
||||||
hash), so lint failures surface in seconds rather than after a full compile.
|
hash), so lint failures surface in seconds rather than after a full compile.
|
||||||
@@ -354,12 +304,8 @@ style conventions are in separate documents:
|
|||||||
`Dockerfile`:
|
`Dockerfile`:
|
||||||
|
|
||||||
```dockerfile
|
```dockerfile
|
||||||
# In every stage ARG CACHEBUST comes right after the steps that install
|
# The steps that install system packages and download Go's modules
|
||||||
# system packages and download Go's modules, or right after FROM in a
|
# come before COPY . ., so a change to the code keeps their layers.
|
||||||
# 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 compile mount Go's build cache, and golangci-lint run
|
# The steps that compile mount Go's build cache, and golangci-lint run
|
||||||
# also mounts golangci-lint's; both survive from build to build.
|
# also mounts golangci-lint's; both survive from build to build.
|
||||||
|
|
||||||
@@ -369,7 +315,6 @@ style conventions are in separate documents:
|
|||||||
WORKDIR /src
|
WORKDIR /src
|
||||||
COPY go.mod go.sum ./
|
COPY go.mod go.sum ./
|
||||||
RUN go mod download
|
RUN go mod download
|
||||||
ARG CACHEBUST
|
|
||||||
COPY . .
|
COPY . .
|
||||||
RUN --mount=type=cache,target=/root/.cache/go-build \
|
RUN --mount=type=cache,target=/root/.cache/go-build \
|
||||||
--mount=type=cache,target=/root/.cache/golangci-lint \
|
--mount=type=cache,target=/root/.cache/golangci-lint \
|
||||||
@@ -385,7 +330,6 @@ style conventions are in separate documents:
|
|||||||
WORKDIR /src
|
WORKDIR /src
|
||||||
COPY go.mod go.sum ./
|
COPY go.mod go.sum ./
|
||||||
RUN go mod download
|
RUN go mod download
|
||||||
ARG CACHEBUST
|
|
||||||
COPY . .
|
COPY . .
|
||||||
RUN --mount=type=cache,target=/root/.cache/go-build \
|
RUN --mount=type=cache,target=/root/.cache/go-build \
|
||||||
status=0; \
|
status=0; \
|
||||||
@@ -410,7 +354,6 @@ style conventions are in separate documents:
|
|||||||
WORKDIR /src
|
WORKDIR /src
|
||||||
COPY go.mod go.sum ./
|
COPY go.mod go.sum ./
|
||||||
RUN go mod download
|
RUN go mod download
|
||||||
ARG CACHEBUST
|
|
||||||
COPY --from=lint /src/go.sum /dev/null
|
COPY --from=lint /src/go.sum /dev/null
|
||||||
COPY --from=test /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.
|
# A tar-stream context keeps the sender's file owners, which git refuses.
|
||||||
@@ -436,7 +379,6 @@ style conventions are in separate documents:
|
|||||||
|
|
||||||
# Runtime stage, and the last one
|
# Runtime stage, and the last one
|
||||||
FROM alpine@sha256:...
|
FROM alpine@sha256:...
|
||||||
ARG CACHEBUST
|
|
||||||
COPY --from=builder /app /usr/local/bin/app
|
COPY --from=builder /app /usr/local/bin/app
|
||||||
ENTRYPOINT ["app"]
|
ENTRYPOINT ["app"]
|
||||||
```
|
```
|
||||||
@@ -452,15 +394,15 @@ style conventions are in separate documents:
|
|||||||
two copies. A plain `docker build .` builds the last stage's chain and
|
two copies. A plain `docker build .` builds the last stage's chain and
|
||||||
nothing else.
|
nothing else.
|
||||||
- Check builds keep these, and none of them can hand back a stale result:
|
- 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
|
- The layers of the system packages and Go's modules. Docker installs
|
||||||
modules. Docker installs the packages again when the base image or the
|
the packages again when the base image or the install line changes.
|
||||||
install line changes. Docker downloads the modules again when `go.mod`
|
Docker downloads the modules again when `go.mod` or `go.sum` changes.
|
||||||
or `go.sum` changes. Go checks every module against `go.sum` as it
|
Go checks every module against `go.sum` as it downloads it, and no
|
||||||
downloads it, and no later build can change a kept layer. The modules
|
later build can change a kept layer. The modules are kept in a layer
|
||||||
are kept in a layer rather than a cache mount. A cache mount is shared
|
rather than a cache mount. A cache mount is shared by every build on
|
||||||
by every build on the host, and Go builds from whatever files the
|
the host, and Go builds from whatever files the mount holds without
|
||||||
mount holds without checking them again (only `go mod verify` does). A
|
checking them again (only `go mod verify` does). A file changed there
|
||||||
file changed there would go unnoticed.
|
would go unnoticed.
|
||||||
- Go's build cache (`/root/.cache/go-build`, where Go keeps it for
|
- Go's build cache (`/root/.cache/go-build`, where Go keeps it for
|
||||||
root), mounted on the steps that compile: `golangci-lint run`, both
|
root), mounted on the steps that compile: `golangci-lint run`, both
|
||||||
`go test` runs and `go build`. Go reuses a compiled package only when
|
`go test` runs and `go build`. Go reuses a compiled package only when
|
||||||
@@ -487,8 +429,8 @@ style conventions are in separate documents:
|
|||||||
(`libvips-dev`, where alpine says `vips-dev`), and delete the package
|
(`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,
|
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
|
on the Debian Go image, installs the libraries its tests need the same
|
||||||
way. Either install goes right after `FROM`, above `ARG CACHEBUST`, so
|
way. Either install goes right after `FROM`, so Docker keeps it until the
|
||||||
Docker keeps it until the base image or the install line changes:
|
base image or the install line changes:
|
||||||
|
|
||||||
```dockerfile
|
```dockerfile
|
||||||
FROM golangci/golangci-lint@sha256:... AS lint
|
FROM golangci/golangci-lint@sha256:... AS lint
|
||||||
@@ -498,7 +440,6 @@ style conventions are in separate documents:
|
|||||||
WORKDIR /src
|
WORKDIR /src
|
||||||
COPY go.mod go.sum ./
|
COPY go.mod go.sum ./
|
||||||
RUN go mod download
|
RUN go mod download
|
||||||
ARG CACHEBUST
|
|
||||||
```
|
```
|
||||||
|
|
||||||
- `.dockerignore` lets `.git` into the build context. It keeps out every git
|
- `.dockerignore` lets `.git` into the build context. It keeps out every git
|
||||||
@@ -539,21 +480,19 @@ style conventions are in separate documents:
|
|||||||
already do.
|
already do.
|
||||||
|
|
||||||
- **A Python `test` phase that installs its packages from `Pipfile.lock` does it
|
- **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 script/ script/`
|
||||||
- `COPY Pipfile Pipfile.lock ./`
|
- `COPY Pipfile Pipfile.lock ./`
|
||||||
- `RUN script/bootstrap`
|
- `RUN script/bootstrap`
|
||||||
|
|
||||||
`ARG CACHEBUST` comes right after them. Docker keeps what that `RUN`
|
Docker keeps what that `RUN` installed until one of these changes:
|
||||||
installed until one of these changes:
|
|
||||||
- the base image
|
- the base image
|
||||||
- `script/`
|
- `script/`
|
||||||
- `Pipfile`
|
- `Pipfile`
|
||||||
- `Pipfile.lock`
|
- `Pipfile.lock`
|
||||||
- a line up to and including the `RUN`
|
- a line up to and including the `RUN`
|
||||||
|
|
||||||
The tests run after `ARG CACHEBUST`, on every check build. In every other
|
The tests run after `COPY . .`.
|
||||||
stage, a step that installs Python packages comes after `ARG CACHEBUST`.
|
|
||||||
- When `script/bootstrap` runs in that step, it installs nothing beyond
|
- When `script/bootstrap` runs in that step, it installs nothing beyond
|
||||||
these:
|
these:
|
||||||
- system packages
|
- system packages
|
||||||
@@ -561,8 +500,7 @@ style conventions are in separate documents:
|
|||||||
- the packages from `Pipfile.lock`
|
- the packages from `Pipfile.lock`
|
||||||
|
|
||||||
`script/bootstrap` installs no Python there: the tests use the
|
`script/bootstrap` installs no Python there: the tests use the
|
||||||
distribution's Python, which a step above it installs. If it installs
|
distribution's Python, which a step above it installs.
|
||||||
anything else there, the step goes after `ARG CACHEBUST`.
|
|
||||||
|
|
||||||
- Debian's Python refuses a system-wide `pip install`, so pipenv goes in a
|
- Debian's Python refuses a system-wide `pip install`, so pipenv goes in a
|
||||||
virtual environment at `$HOME/.pipenv`. `script/bootstrap` creates it with
|
virtual environment at `$HOME/.pipenv`. `script/bootstrap` creates it with
|
||||||
@@ -644,7 +582,6 @@ style conventions are in separate documents:
|
|||||||
COPY script/ script/
|
COPY script/ script/
|
||||||
COPY Pipfile Pipfile.lock ./
|
COPY Pipfile Pipfile.lock ./
|
||||||
RUN script/bootstrap
|
RUN script/bootstrap
|
||||||
ARG CACHEBUST
|
|
||||||
COPY . .
|
COPY . .
|
||||||
RUN timeout 90 sh -c 'pipenv run pytest || { \
|
RUN timeout 90 sh -c 'pipenv run pytest || { \
|
||||||
echo "--- Rerunning with -v for details ---"; \
|
echo "--- Rerunning with -v for details ---"; \
|
||||||
@@ -663,20 +600,16 @@ style conventions are in separate documents:
|
|||||||
A new push then cancels the older run on the same branch, queued or running,
|
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.
|
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,
|
`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
|
so a successful run means every check passed. The `check` job sets
|
||||||
carry the same guarantee, because its gate phases may come from the cache. The
|
`timeout-minutes: 20`, so a hung build frees the shared runner after 20
|
||||||
image build gets a `CACHEBUST` value of its own and so runs the gate phases a
|
minutes. That allows for the three Docker builds described above, each held to
|
||||||
second time. That is the price of the rule above, and it is worth paying. The
|
the 5-minute Docker build limit below, plus the bootstrap. Those builds are
|
||||||
image that ships is built from a run of its own gates rather than from a cache
|
the test phase, the lint phase, then the image. A separate workflow limited to
|
||||||
entry. The `check` job sets `timeout-minutes: 20`, so a hung build frees the
|
`main` by a `branches` list under `on: push` cannot be checked by review. To
|
||||||
shared runner after 20 minutes. That allows for the three Docker builds
|
try a change to it, add the feature branch to that list and push, then remove
|
||||||
described above, each held to the 5-minute Docker build limit below, plus the
|
the branch from the list again before merging. Keep any job in it that
|
||||||
bootstrap. Those builds are the test phase, the lint phase, then the image. A
|
publishes behind `if: github.ref_name == 'main'`, so the run from the feature
|
||||||
separate workflow limited to `main` by a `branches` list under `on: push`
|
branch publishes nothing.
|
||||||
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:
|
- Use platform-standard formatters:
|
||||||
- `black` for Python
|
- `black` for Python
|
||||||
@@ -781,14 +714,13 @@ style conventions are in separate documents:
|
|||||||
tests. It leaves the build cache alone, so it costs the runtime of the suite
|
tests. It leaves the build cache alone, so it costs the runtime of the suite
|
||||||
and no recompilation.
|
and no recompilation.
|
||||||
|
|
||||||
That cache is Go's own, separate from Docker's layer cache. Go stores a
|
That cache is Go's own. Go stores a passing result in its cache directory
|
||||||
passing result in its cache directory (`GOCACHE`). When the same tests run
|
(`GOCACHE`). When the same tests run again on unchanged code, it prints that
|
||||||
again on unchanged code, it prints that result, marked `(cached)`, without
|
result, marked `(cached)`, without running them. The directory lasts from
|
||||||
running them. The directory lasts from one run to the next on a developer's
|
one run to the next on a developer's machine, where this target runs. The
|
||||||
machine, where this target runs. The directory also lasts in the `test`
|
directory also lasts in the `test` phase of the `Dockerfile`, which mounts
|
||||||
phase of the `Dockerfile`, which mounts it to keep compiled packages between
|
it to keep compiled packages between check builds, so the phase's `go test`
|
||||||
check builds, so the phase's `go test` runs carry `-count=1` too. A new
|
runs carry `-count=1` too.
|
||||||
`CACHEBUST` value (above) is what makes that step run on an unchanged tree.
|
|
||||||
|
|
||||||
Python example:
|
Python example:
|
||||||
|
|
||||||
@@ -891,9 +823,7 @@ style conventions are in separate documents:
|
|||||||
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
||||||
[ -n "$version" ] || version="unknown"
|
[ -n "$version" ] || version="unknown"
|
||||||
tag="$(script/projectname)"
|
tag="$(script/projectname)"
|
||||||
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
|
docker build --build-arg VERSION="$version" -t "$tag" .
|
||||||
--build-arg VERSION="$version" \
|
|
||||||
-t "$tag" .
|
|
||||||
```
|
```
|
||||||
|
|
||||||
`--always` makes an untagged repo yield an abbreviated commit hash rather
|
`--always` makes an untagged repo yield an abbreviated commit hash rather
|
||||||
|
|||||||
+1
-9
@@ -2,12 +2,6 @@
|
|||||||
# script/cibuild: run the CI build. It bootstraps first: a CI runner
|
# script/cibuild: run the CI build. It bootstraps first: a CI runner
|
||||||
# checks out and runs this and nothing else, and script/fmt-check runs
|
# checks out and runs this and nothing else, and script/fmt-check runs
|
||||||
# the formatter on the host, which a pristine checkout cannot do.
|
# the formatter on the host, which a pristine checkout cannot do.
|
||||||
# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
|
|
||||||
# line, since a cached gate phase is a check that did not run; unlike
|
|
||||||
# --no-cache, it keeps the layers above that line and the cache mounts.
|
|
||||||
# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
|
|
||||||
# before every step that lints, tests or compiles; a stage without that
|
|
||||||
# line is served from cache on an unchanged tree, with no warning.
|
|
||||||
set -eu
|
set -eu
|
||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||||
@@ -25,9 +19,7 @@ main() {
|
|||||||
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
||||||
[ -n "$version" ] || version="unknown"
|
[ -n "$version" ] || version="unknown"
|
||||||
tag="$("$SCRIPT_DIR/projectname")"
|
tag="$("$SCRIPT_DIR/projectname")"
|
||||||
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
|
docker build --build-arg VERSION="$version" -t "$tag" .
|
||||||
--build-arg VERSION="$version" \
|
|
||||||
-t "$tag" .
|
|
||||||
}
|
}
|
||||||
|
|
||||||
main "$@"
|
main "$@"
|
||||||
+1
-9
@@ -1,12 +1,6 @@
|
|||||||
#!/bin/sh
|
#!/bin/sh
|
||||||
# script/docker: build the Docker image tagged with the project name.
|
# script/docker: build the Docker image tagged with the project name.
|
||||||
# Identical in all repos; the tag comes from script/projectname.
|
# Identical in all repos; the tag comes from script/projectname.
|
||||||
# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
|
|
||||||
# line, since a cached gate phase is a check that did not run; unlike
|
|
||||||
# --no-cache, it keeps the layers above that line and the cache mounts.
|
|
||||||
# This relies on every stage of the Dockerfile declaring ARG CACHEBUST
|
|
||||||
# before every step that lints, tests or compiles; a stage without that
|
|
||||||
# line is served from cache on an unchanged tree, with no warning.
|
|
||||||
set -eu
|
set -eu
|
||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||||
@@ -22,9 +16,7 @@ main() {
|
|||||||
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
|
||||||
[ -n "$version" ] || version="unknown"
|
[ -n "$version" ] || version="unknown"
|
||||||
tag="$("$SCRIPT_DIR/projectname")"
|
tag="$("$SCRIPT_DIR/projectname")"
|
||||||
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
|
docker build --build-arg VERSION="$version" -t "$tag" .
|
||||||
--build-arg VERSION="$version" \
|
|
||||||
-t "$tag" .
|
|
||||||
}
|
}
|
||||||
|
|
||||||
main "$@"
|
main "$@"
|
||||||
@@ -8,8 +8,8 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
|
|||||||
main() {
|
main() {
|
||||||
cd "$ROOT"
|
cd "$ROOT"
|
||||||
hook=".git/hooks/pre-commit"
|
hook=".git/hooks/pre-commit"
|
||||||
printf '#!/bin/sh\nset -e\nscript/precommit\n' > .git/hooks/pre-commit
|
printf '#!/bin/sh\nset -e\nscript/precommit\n' > "$hook"
|
||||||
chmod +x .git/hooks/pre-commit
|
chmod +x "$hook"
|
||||||
echo "pre-commit hook installed: runs script/precommit"
|
echo "pre-commit hook installed: runs script/precommit"
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
+4
-13
@@ -1,18 +1,11 @@
|
|||||||
#!/bin/sh
|
#!/bin/sh
|
||||||
# script/lint: run the linter. Linting is a phase of the Dockerfile and
|
# script/lint: run the linter. Linting is a phase of the Dockerfile and
|
||||||
# this builds that phase alone; the linter is never installed or run on
|
# this builds that phase; the linter is never installed or run on
|
||||||
# a developer host, where a shared result cache and a host-global lock
|
# a developer host, where a shared result cache and a host-global lock
|
||||||
# make its answer untrustworthy.
|
# make its answer untrustworthy.
|
||||||
#
|
#
|
||||||
# The phase is not the last stage in the file, so it is built only when
|
# --target builds the lint phase and the stages it depends on, nothing
|
||||||
# --target names it. A new CACHEBUST value reruns every RUN step after
|
# else. --output type=cacheonly writes no image, since nothing uses one.
|
||||||
# the ARG CACHEBUST line, since a cached lint layer is a lint that did
|
|
||||||
# not run; unlike --no-cache, it keeps the layers above that line and
|
|
||||||
# the cache mounts. This relies on every stage of the Dockerfile
|
|
||||||
# declaring ARG CACHEBUST before every step that lints, tests or
|
|
||||||
# compiles; 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
|
set -eu
|
||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||||
@@ -20,9 +13,7 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
|
|||||||
|
|
||||||
main() {
|
main() {
|
||||||
cd "$ROOT"
|
cd "$ROOT"
|
||||||
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
|
docker build --target lint --output type=cacheonly .
|
||||||
--target lint \
|
|
||||||
--output type=cacheonly .
|
|
||||||
}
|
}
|
||||||
|
|
||||||
main "$@"
|
main "$@"
|
||||||
+5
-12
@@ -1,14 +1,9 @@
|
|||||||
#!/bin/sh
|
#!/bin/sh
|
||||||
# script/test: run the test suite. Testing is a phase of the Dockerfile
|
# script/test: run the test suite. Testing is a phase of the Dockerfile
|
||||||
# and this builds that phase alone, on the same terms as script/lint:
|
# and this builds that phase, on the same terms as script/lint:
|
||||||
# --target because a phase that is not the last stage is built only when
|
# --target so that only the test phase and the stages it depends on are
|
||||||
# named, and a new CACHEBUST value because a cached test layer is a test
|
# built, and --output type=cacheonly so that no image is written, since
|
||||||
# that did not run; unlike --no-cache, it keeps the layers above the ARG
|
# nothing uses one.
|
||||||
# CACHEBUST line and the cache mounts. This relies on every stage of the
|
|
||||||
# Dockerfile declaring ARG CACHEBUST before every step that lints, tests
|
|
||||||
# or compiles; 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
|
set -eu
|
||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
|
||||||
@@ -16,9 +11,7 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
|
|||||||
|
|
||||||
main() {
|
main() {
|
||||||
cd "$ROOT"
|
cd "$ROOT"
|
||||||
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
|
docker build --target test --output type=cacheonly .
|
||||||
--target test \
|
|
||||||
--output type=cacheonly .
|
|
||||||
}
|
}
|
||||||
|
|
||||||
main "$@"
|
main "$@"
|
||||||
Reference in new issue
Block a user