From 3e2e8803309c20e50ee9b7b3935d45998b1e337e Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Mon, 9 Nov 2026 07:01:26 +0000 Subject: [PATCH] REPO_POLICIES: apply the wordings from the latest compaction review Applies the "Acceptable" wording of each of the seven findings at https://git.eeqj.de/sneak/prompts/pulls/159#issuecomment-171836, as https://git.eeqj.de/sneak/prompts/pulls/159#issuecomment-171841 says. `TODO.md` carries the new size: 982 lines and 7,281 words. Model: opus-5-5 --- TODO.md | 2 +- prompts/REPO_POLICIES.md | 49 ++++++++++++++++++++++++---------------- 2 files changed, 30 insertions(+), 21 deletions(-) diff --git a/TODO.md b/TODO.md index 158489f..a7cf561 100644 --- a/TODO.md +++ b/TODO.md @@ -22,7 +22,7 @@ fmt-check, and commit. # Completed Steps - 2026-11-09: Compacted `prompts/REPO_POLICIES.md` from 1,165 lines and 8,556 - words to 973 lines and 7,265 words + words to 982 lines and 7,281 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 diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index f8d9ffb..8775f2c 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -215,9 +215,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 @@ -338,9 +338,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` @@ -383,9 +383,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` @@ -451,10 +455,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/` @@ -511,8 +519,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 @@ -541,7 +550,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 @@ -559,8 +568,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, @@ -647,8 +656,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.