diff --git a/TODO.md b/TODO.md index 5f69b19..18d570f 100644 --- a/TODO.md +++ b/TODO.md @@ -21,6 +21,13 @@ fmt-check, and commit. # Completed Steps +- 2026-11-09: Compacted `prompts/REPO_POLICIES.md` from 1,182 lines and 8,696 + words to 998 lines and 7,418 words + (https://git.eeqj.de/sneak/prompts/issues/158). Every rule keeps its meaning. + The rules now sit under headings, the pinning rule first. Each rule that was + stated in several places is stated once. The Makefile copies of the Go and + Python test commands are gone, because the `Dockerfile` examples carry the + same commands. Both checklists name the `.golangci.yml` section. - 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 @@ -32,20 +39,6 @@ fmt-check, and commit. 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: Compacted `prompts/REPO_POLICIES.md` from 1,145 lines and 8,427 - words to 1,066 lines and 7,812 words -- 2026-11-09: Compacted `prompts/REPO_POLICIES.md` from 1,165 lines and 8,556 - words to 973 lines and 7,265 words - (https://git.eeqj.de/sneak/prompts/issues/158). Every rule keeps its meaning. - The rules now sit under headings, the pinning rule first. Each rule that was - stated in several places is stated once. The Makefile copies of the Go and - Python test commands are gone, because the `Dockerfile` examples carry the - same commands. Both checklists name the `.golangci.yml` section. -- 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 diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index 32fac4a..57553bb 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -231,9 +231,9 @@ Use `yarn`, not `npm`. no node and no yarn there. The stages in the `prompts` repo's `examples/go.Dockerfile` and `examples/python-test-phase.Dockerfile` are such stages. -- It installs the node packages with `yarn install --immutable`, which fails - when a package's `checksum` is wrong, or when `package.json` is out of step - with `yarn.lock`. +- `script/bootstrap` installs the node packages with `yarn install --immutable`, + which fails when a package's `checksum` is wrong, or when `package.json` is + out of step with `yarn.lock`. - Each repository commits the yarn that runs. `yarnPath` in `.yarnrc.yml` points at the release file in `.yarn/releases/`. The distribution's yarn only starts that file, and that file does the work. So Alpine's yarn 1 and Debian 13's @@ -354,9 +354,9 @@ What each stage installs: running `script/bootstrap`. Only system packages may be installed inline above it, so that check builds keep them; the `prompts` repo's own `Dockerfile` does this. -- A stage that runs `script/bootstrap` first COPYs `script/` and the dependency - manifests it needs: `go.mod` and `go.sum`, for example, or the four yarn files - named above. +- A stage that runs `script/bootstrap` COPYs `script/` and the dependency + manifests it needs before running it: `go.mod` and `go.sum`, for example, or + the four yarn files named above. ## `CACHEBUST` @@ -399,9 +399,13 @@ step that also installs anything else comes after `ARG CACHEBUST` too. A 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, then revert the defect. A green run alone - shows neither that the check ran nor that it covers what it should. +- 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. ## Canonical Go `Dockerfile` @@ -467,10 +471,14 @@ Key points: ## Python `test` phase **A Python `test` phase that installs its packages from `Pipfile.lock` does it -above `ARG CACHEBUST`, so check builds keep them.** The steps are -`COPY script/ script/`, `COPY Pipfile Pipfile.lock ./` and -`RUN script/bootstrap`, with `ARG CACHEBUST` right after them. Docker keeps what -that `RUN` installed until one of these changes: +above `ARG CACHEBUST`, so check builds keep them.** The steps are: + +- `COPY script/ script/` +- `COPY Pipfile Pipfile.lock ./` +- `RUN script/bootstrap` + +`ARG CACHEBUST` comes right after them. Docker keeps what that `RUN` installed +until one of these changes: - the base image - `script/` @@ -527,8 +535,9 @@ checked for it covers them. System packages, Python among them, are not fixed by a hash. They keep the versions the package manager gave when the layer was built; a new install may get newer ones. -As with Go's modules, the packages are kept in a layer, not a cache mount, which -every build on the host shares and nothing checks again. +As with Go's modules, the packages are kept in a layer, not a cache mount. A +cache mount is shared by every build on the host, and nothing checks its files +again. A Python repository's `script/bootstrap` adds these lines in `main`, above the last `echo`. The `ensurepip` test fails when python is missing, and also when @@ -557,7 +566,7 @@ In `examples/python-test-phase.Dockerfile`, `script/bootstrap` finds `make`, `git`, python and venv already installed. The Python `test` phase example is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/python-test-phase.Dockerfile`. -Run from a `make test` target on a host, the test command in +A `make test` target on a host that runs the command in `examples/python-test-phase.Dockerfile`: - does not stop on Ctrl-C. It goes on until the tests end or the 90 seconds run @@ -575,8 +584,8 @@ Run from a `make test` target on a host, the test command in (`v1.2.3-4-gabc1234`), on a later commit - the short commit, when no tag is reachable -The stage that compiles derives it from the `.git` in the build context, as the -`prompts` repo's `examples/go.Dockerfile` shows: +The stage that compiles derives the version from the `.git` in the build +context, as the `prompts` repo's `examples/go.Dockerfile` shows: - It takes the version from the `VERSION` build argument when one is given, otherwise from `git describe`. `ARG VERSION` is declared in that stage, @@ -663,8 +672,8 @@ The workflow sets these: - **`script/cibuild` runs `script/bootstrap` first**, because the workflow checks out the repo and runs nothing else, while `script/fmt-check` runs the - formatter on the host. Without it, a pristine checkout dies there, after the - containerised gates have passed. + formatter on the host. On a pristine checkout with nothing installed, the run + dies there, after the containerised gates have passed. - Its three Docker builds are the test phase, the lint phase, then the image. So a successful run means every check passed, which a bare `docker build .` does not show.