REPO_POLICIES: Pinned tools
check / check (push) Canceled after 0s

The POSIX sh rule joins the list of what the canonical form does, and
two sentences lose filler ("installing into a clean image", "which
then succeeds while no caller sees any change"); each step of the
canonical form and the go install rule stay.

Model: opus-5-5
This commit is contained in:
clawbot committed 2026-11-16 23:40:00 +00:00
1 parent 410b9b1621
commit e13195dd84
1 file changed
+10 -10
+10 -10
View File
@@ -273,12 +273,14 @@ style conventions are in separate documents:
the first two, the install fails, and Alpine's yarn 1 says to enable the first two, the install fails, and Alpine's yarn 1 says to enable
corepack. Never do that; copy the missing files instead. corepack. Never do that; copy the missing files instead.
## Pinned tools
- **`script/bootstrap` installs a pinned tool by comparing versions, never by - **`script/bootstrap` installs a pinned tool by comparing versions, never by
testing presence.** An `if ! command -v <tool>; then install; fi` guard tests testing presence.** An `if ! command -v <tool>; then install; fi` guard tests
`PATH` only. On an already-provisioned machine the pin is then inert, and a `PATH` only. On an already-provisioned machine the pin is then inert, and a
version bump is a silent no-op. The Dockerfile, installing into a clean image, version bump is a silent no-op. The Dockerfile's clean image still gets the
gets the pinned version, so a local `make check` and `make docker` can pinned version, so a local `make check` and `make docker` can disagree about
disagree about what the tool even is. The canonical form: what the tool even is. The canonical form:
- compares the installed version against the pin over the **whole** version - compares the installed version against the pin over the **whole** version
token. A parser that stops at the first `-` reports `2.12.2` for a host token. A parser that stops at the first `-` reports `2.12.2` for a host
running `2.12.2-rc1` and skips the install. running `2.12.2-rc1` and skips the install.
@@ -290,16 +292,14 @@ style conventions are in separate documents:
So a failure causes a redundant install, never a skipped one. So a failure causes a redundant install, never a skipped one.
- after installing, re-resolves the binary the way callers do, with - after installing, re-resolves the binary the way callers do: `hash -r`,
`hash -r` and then through `PATH`, not through the directory the installer then `PATH`, not the directory the installer wrote to. A shadowing binary
wrote to. A shadowing binary can hide an install, which then succeeds can hide an install that reported success. In that case it fails and names
while no caller sees any change. In that case it fails and names the the resolved path.
resolved path.
- is actually called, and prints the version on both success paths. A - is actually called, and prints the version on both success paths. A
function defined and never invoked has the same exit status and the same function defined and never invoked has the same exit status and the same
empty output as one that worked. empty output as one that worked.
- stays POSIX sh: no arrays, no `[[`, no `grep -P`.
Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
A Go tool a repo needs on the host is installed with `go install` pinned to A Go tool a repo needs on the host is installed with `go install` pinned to
a commit hash (`go install <package>@<commit hash>`). It is never tracked as a commit hash (`go install <package>@<commit hash>`). It is never tracked as