Author SHA1 Message Date
sneak e34c7bf42d test/update-policy.sh: make the older copy shorter than the new script
check / check (push) Successful in 13s
The script moves each fetched file into place so that the running
script is replaced, never rewritten in place: rewritten in place, the
shell would read the new file's tail as commands. The test's older copy
was the new script plus a line, so it was longer, and that tail was
empty: writing the files with cat instead of mv left the tests green.
The older copy is now the new script without its comment lines, and the
test fails without the mv.

Model: opus-5-5
2026-11-18 22:01:04 +00:00
sneak d8a4a2733a test/update-policy.sh: check that other staged changes stay out of the commit
check / check (push) Successful in 12s
The script commits only the listed paths, but no test staged anything
else, so dropping the pathspec from its git commit left the tests green
while the commit swept in whatever the person had staged. The first
scenario now stages a change to README.md and checks that the commit
holds only the listed files and that the change is still staged.

Model: opus-5-5
2026-11-18 21:44:44 +00:00
sneak 6378311ac5 script/update-policy: put the code in a main function
check / check (push) Successful in 1m27s
The script ran its code at the top level. prompts/CODE_STYLEGUIDE.md
says to put all shell code in functions, with a main called at the
bottom, and every other script in script/ does. The code now sits in
main(), and the last line calls it.

Model: opus-5-5
2026-11-18 21:31:09 +00:00
sneak 29496c2586 test/update-policy.sh: make the stub wget drop the execute bit
check / check (push) Successful in 11s
The stub wget copied each file with cp, which keeps the source's
execute bit, so the "script not executable" assertion could not fail:
removing the chmod 755 from script/update-policy left the tests green.
Real wget writes a new file without the execute bit. The stub now
writes with cat, as wget does, and the test fails without the chmod.

Model: opus-5-5
2026-11-18 21:15:46 +00:00
sneak 47b35661a2 Replace script/update-policy with a short wget-and-commit script (closes #165)
check / check (push) Successful in 13s
The script fetches a fixed list of three files from the main branch of
prompts with wget: docs/REPO_POLICIES.md, docs/CODE_STYLEGUIDE.md and
itself. It moves them into place and commits them. It does not push. It
stops before anything is replaced when a fetch fails, when a listed file
has uncommitted changes, and when REPO_POLICIES.md is still at the repo
root. It runs under busybox.

The line-keeping rules, the hash argument and the push are gone. The
policies and checklists say so, and name docs/REPO_POLICIES.md as the
file's place.

Model: opus-5-5
2026-11-18 20:56:57 +00:00
clawbot 630437e620 REPO_POLICIES: move the example Dockerfiles into examples/
check / check (push) Successful in 13s
Each fenced dockerfile block moves byte for byte into its own file
under examples/, and one sentence links the file where the block
stood, as sneak ruled at
#159 (comment).
Phrases that pointed at a block by position now name the file, here
and in both checklists. README.md names the folder. No rule changes.

Model: opus-5-5
2026-11-18 21:54:17 +01:00
clawbotandsneak 22d08ecd0e Remove the build-cache text from the policies (closes #179) (#180)
check / check (push) Successful in 1m32s
Closes #179

Cache busting was a one-time error, already fixed; the policy should not record it. This removes every sentence about Docker's build cache for check builds:

- `prompts/REPO_POLICIES.md`: the "Check builds use Docker's normal cache" rule, with its prune warning and its planted-defect rule; the sentence saying the image build reuses the gate phases; "separate from Docker's layer cache" in the `-count=1` passage.
- `README.md`: the paragraph on the builds using Docker's normal cache.
- `prompts/EXISTING_REPO_CHECKLIST.md`: the item forbidding `--no-cache` and `CACHEBUST`.

Disclosures:

- The planted-defect rule went: it was added in October inside the `--no-cache` rule, after cache busting began in September, so it does not predate it.
- Judgement call: text on Go's build cache mounts, kept module and Python package layers, golangci-lint's cache and `-count=1` stays. Those are sneak's separate rulings on what check builds keep (#130, #133), not cache busting. Removing them later is a text-only revert.
- The checklists' "plant a lint violation" items stay: they test that the gate phases are reachable from the final stage, not caching.

Model: opus-5-5
Co-authored-by: sneak <sneak@sneak.berlin>
Reviewed-on: #180
Co-authored-by: clawbot <35+clawbot@noreply.example.org>
2026-11-18 21:14:21 +01:00
clawbot 964d973e3c Check builds use Docker's normal cache (closes #177)
check / check (push) Successful in 12s
Drop the CACHEBUST build argument from script/lint, script/test,
script/docker, script/cibuild and every Dockerfile stage. REPO_POLICIES
now says check builds use Docker's normal cache: an unchanged tree reuses
each step's stored result, which Docker keeps only for steps that
succeeded. The rules on placing ARG CACHEBUST and re-vendoring it in one
commit are gone; the rule that a planted defect proves a new or changed
check stays. The README, the Go style guide and both checklists restated
the cache-busting rules and are updated to match. The existing-repo
checklist asks that no script pass --no-cache or CACHEBUST.

Model: opus-5-5
2026-11-16 23:09:07 +01:00
clawbot 1ad7ae14be CODE_STYLEGUIDE_GO: propose naming rules for packages and exported names (closes #174) (#175)
check / check (push) Successful in 1m46s
Proposal for the naming-rules issue, #174: a Naming section in `prompts/CODE_STYLEGUIDE_GO.md`, twenty-seven rules, each with its reason. Nothing is renamed in any repo until sneak approves or amends them.

Where each rule comes from:

- Package names
    - Named for what the package provides; lowercase with words run together; only familiar abbreviations: Effective Go and the Go blog post "Package names".
    - No `model`, `util`, `common`, `types`, `helpers`, `api` and the like, and splitting such packages: sneak on `model`; "Package names"; Go Code Review Comments; the Go Style Guide, which also lists `model`.
    - No name a caller wants for a variable or a standard package has: "Package names"; the Go Style Guide.
    - Directory named as the package: Effective Go.
    - Test-support packages named like `storetest`; import names: the Go Style Guide.
- Exported names
    - No package name repeated; the same plain name in two packages: Effective Go; "Package names"; Code Review Comments.
    - Types in a name; noun or verb; `Fetch` for a getter that reads from a database or the network: the Go Style Guide.
    - No `Get`; `er` interfaces; well-known method names: Effective Go.
    - Initialisms; MixedCaps constants: Code Review Comments; the Go Style Guide.
    - `ErrNotFound` and `NotFoundError`: the Go wiki page "Errors", which is not one of the four sources.
- Local names (length by scope; receivers): Code Review Comments; the Go Style Guide.

The first comment lists the renames and the judgement calls.

Model: fable-5-2 (proposal); opus-5-5 (rework)
Reviewed-on: #175
Co-authored-by: clawbot <35+clawbot@noreply.example.org>
2026-11-16 22:02:05 +01:00
clawbot 69d38ba6de README: remove the Template Repos section (closes #153)
check / check (push) Successful in 1m47s
Every repository the section linked returned 404 to a signed-out
reader: `template-app-js` and `template-app-python` do not exist, and
`template-app-go` is private. The section is gone, intro included.

Model: opus-5-5
2026-11-15 17:39:12 +01:00
clawbot 198b896a53 Correct the phase-build comments in script/lint and script/test (closes #141)
check / check (push) Successful in 35s
The comments said a phase that is not the last stage is built only when
--target names it. The canonical Dockerfile's last stage copies from both
phases, so a plain build builds them too. The comments now say what
--target does in every repository: it builds that phase and the stages
it depends on, nothing else. The headers no longer say each script
builds its phase alone, which is false wherever the phase depends on
another stage.

Model: opus-5-5
2026-11-15 17:09:08 +01:00
clawbot 11245b85ca script/install-precommit: write the hook through $hook (closes #139)
check / check (push) Successful in 1m41s
The script set hook and then repeated the path literally, so shellcheck
reported the variable as unused (SC2034).

Model: opus-5-5
2026-11-15 14:23:52 +01:00
clawbot 02632a5682 Drop the TODO.md union-merge rule (closes #169)
check / check (push) Successful in 1m46s
The rule and its comment existed only so concurrent PRs could each add a
Completed Steps entry to `TODO.md`. That work log is gone; `TODO.md` now
holds only open work, so it merges normally again.

Model: opus-5-5
2026-11-15 07:38:36 +01:00
clawbot fdf517a1f7 TODO.md: remove the work log, keep only open work (closes #167)
check / check (push) Successful in 1m44s
Drop the Completed Steps log and the finished "commit this TODO.md"
item. Git keeps the history. The Workflow section now says to delete
the finished Next Step, as the standard Workflow block does.

Model: opus-5-5
2026-11-15 07:08:44 +01:00
18 changed files with 975 additions and 2192 deletions

No files matched your search

-5
View File
@@ -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/releases/** binary
+4 -10
View File
@@ -2,18 +2,14 @@
# lint` or `script/lint`, which are themselves a docker build and would
# recurse into a daemon that does not exist in a build step.
#
# In every stage, ARG CACHEBUST comes right after the step that installs
# system packages. script/ passes a new value on every build. That value
# reruns every RUN step below the ARG line, and the install step keeps
# its layer. node and yarn come from the distribution, which is trusted,
# 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.
# node and yarn come from the distribution, which is trusted, 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
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS lint
RUN apk add --no-cache git make nodejs-current yarn
ARG CACHEBUST
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
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS test
RUN apk add --no-cache git make nodejs-current yarn
ARG CACHEBUST
WORKDIR /app
@@ -53,7 +48,6 @@ RUN timeout 90 test/update-policy.sh
# alpine 3.24.3, 2026-11-04
FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
RUN apk add --no-cache git make nodejs-current yarn
ARG CACHEBUST
WORKDIR /app
+11 -46
View File
@@ -116,12 +116,10 @@ alpine. We provide:
`script/bootstrap`, then `script/install-precommit`
- `script/projectname` — output the project name (our own extension); used by
`script/docker` for the image tag
- `script/test` —
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target test --output type=cacheonly .`,
- `script/test` — `docker build --target test --output type=cacheonly .`,
building the `test` phase of the `Dockerfile`, which runs
`test/update-policy.sh`, without writing an image
- `script/lint` —
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target lint --output type=cacheonly .`,
- `script/lint` — `docker build --target lint --output type=cacheonly .`,
building the `lint` phase, which runs prettier over the markdown files,
without writing an image
- `script/fmt` — format all markdown files with prettier (writes; native, not in
@@ -129,41 +127,23 @@ alpine. We provide:
- `script/fmt-check` — check formatting (read-only; native)
- `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
extension); builds no image of its own
- `script/docker` —
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t prompts .`,
- `script/docker` — `docker build --build-arg VERSION="$version" -t prompts .`,
the tag coming from `script/projectname` (byte-identical across repos)
- `script/cibuild` — cd to the repo root, run `script/bootstrap`, run
`script/check`, compute `version` from `git describe`, then
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t prompts .`
(what CI runs; it bootstraps because CI checks out and runs this alone while
`script/fmt-check` is native)
`docker build --build-arg VERSION="$version" -t prompts .` (what CI runs; it
bootstraps because CI checks out and runs this alone while `script/fmt-check`
is native)
- `script/precommit` — run by the git pre-commit hook (our own extension); calls
`script/check`
- `script/install-precommit` — installs the git pre-commit hook (our own
extension); `make hooks` shims to it
- `script/update-policy` — fetch the vendored policy files from this repo,
commit them and push (our own extension); it is for the repos that vendor them
and stops when run here
- `script/update-policy` — fetch the shared policy files from this repo and
commit them, without pushing (our own extension); it is for the repos that
carry them and stops when run here
`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
LLM prompts, especially development policies, benefit from version control and a
@@ -175,23 +155,8 @@ share, and evolve prompts across projects.
The repository is a collection of Markdown files organized in the `prompts/`
subdirectory. Each file contains one or more related prompts or policy
documents. There is no build step or runtime component; the prompts are consumed
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.).
by copying them into other projects or referencing them directly. `examples/`
holds the example `Dockerfile` files that `prompts/REPO_POLICIES.md` links to.
## See Also
+1 -427
View File
@@ -2,7 +2,7 @@
- branch (from `main`)
- 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
- commit (`TODO.md` changes in the same commit as the work)
- 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
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
- 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.
- Add more prompt templates for common development tasks (from README TODO).
@@ -0,0 +1,7 @@
FROM golangci/golangci-lint@sha256:... AS lint
RUN apt-get update \
&& apt-get install -y --no-install-recommends libvips-dev \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
+77
View File
@@ -0,0 +1,77 @@
# The steps that install system packages and download Go's modules
# come before COPY . ., so a change to the code keeps their layers.
# The steps that compile mount Go's build cache, and golangci-lint run
# also mounts golangci-lint's; both survive from build to build.
# Lint phase
# golangci/golangci-lint:v2.x.x, YYYY-MM-DD
FROM golangci/golangci-lint@sha256:... AS lint
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN --mount=type=cache,target=/root/.cache/go-build \
--mount=type=cache,target=/root/.cache/golangci-lint \
golangci-lint run --config .golangci.yml ./...
# Test phase. -race needs cgo and so a C compiler, which the Debian Go
# image ships and the alpine one does not. -count=1 because the mounted
# cache also holds test results, which go test would otherwise replay.
# A first run that timed out gets no rerun, because a rerun would only
# wait for the same hang.
# golang:1.x, YYYY-MM-DD
FROM golang@sha256:... AS test
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN --mount=type=cache,target=/root/.cache/go-build \
status=0; \
output=$(go test -count=1 -timeout 90s -race -cover ./... 2>&1) || status=$?; \
printf '%s\n' "$output"; \
test "$status" -eq 0 && exit 0; \
case "$output" in \
*"panic: test timed out"*|*"*** Test killed"*) exit 1 ;; \
esac; \
echo "--- Rerunning with -v for details ---"; \
go test -count=1 -timeout 90s -race -v ./...; \
exit 1
# Build stage. Nothing is wanted from either phase above; the copies
# are what make BuildKit build them first, so nothing after them can
# run unless lint and test passed.
# golang:1.x-alpine, YYYY-MM-DD
FROM golang@sha256:... AS builder
# git comes from the base image's own distribution package index, which
# is trusted, so it needs no version and no hash.
RUN apk add --no-cache git
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY --from=lint /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.
RUN git config --system --add safe.directory /src
COPY . .
# The VERSION build arg when one is given, otherwise
# `git describe --tags --always` on the .git in the build context. With
# .git present, a version that is still empty, dev or unknown fails the
# build: git is missing or could not read the checkout.
ARG VERSION
RUN --mount=type=cache,target=/root/.cache/go-build \
VERSION="${VERSION:-$(git describe --tags --always)}"; \
if [ -e .git ]; then \
case "$VERSION" in ""|dev|unknown) \
echo "version is '$VERSION' although .git is present" >&2; \
exit 1 ;; \
esac; \
fi; \
CGO_ENABLED=0 go build -trimpath \
-ldflags="-s -w -X main.Version=${VERSION}" \
-o /app ./cmd/app/
# Runtime stage, and the last one
FROM alpine@sha256:...
COPY --from=builder /app /usr/local/bin/app
ENTRYPOINT ["app"]
+23
View File
@@ -0,0 +1,23 @@
# Test phase. Both pytest runs share one 90-second timeout, so a hang
# uses it once and gets no rerun.
# debian:trixie-slim, YYYY-MM-DD
FROM debian@sha256:... AS test
# Python, pip and venv come from the distribution, which is trusted, so
# they need no version and no hash. make and git are base tools that
# script/bootstrap installs when they are missing. Installed here, they
# stay in their own layer when script/ changes.
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates make git \
python3 python3-venv \
&& rm -rf /var/lib/apt/lists/*
# script/bootstrap installs pipenv in a virtual environment at
# $HOME/.pipenv, and the tests below run that pipenv.
ENV PATH=/root/.pipenv/bin:$PATH
WORKDIR /app
COPY script/ script/
COPY Pipfile Pipfile.lock ./
RUN script/bootstrap
COPY . .
RUN timeout 90 sh -c 'pipenv run pytest || { \
echo "--- Rerunning with -v for details ---"; \
pipenv run pytest -v; exit 1; }'
+120 -10
View File
@@ -1,6 +1,6 @@
---
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`.
@@ -113,13 +113,7 @@ last_modified: 2026-11-07
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
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`
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.
linted, and its tests run.
1. Every repo must have a `Makefile`. See
[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.
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
`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 {
SendErrorResponse(w, MSGenericError)
SendErrorResponse(w, ErrBadRequest)
return
}
@@ -487,6 +481,122 @@ last_modified: 2026-11-07
releasable". "Releasable" in this context means that it builds and functions
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)
1. For any internet-facing http server, set appropriate timeouts and limits to
+21 -53
View File
@@ -1,6 +1,6 @@
---
title: Existing Repo Checklist
last_modified: 2026-11-09
last_modified: 2026-11-18
---
Use this checklist when beginning work in a repo that may not yet conform to our
@@ -22,7 +22,7 @@ with your task.
- [ ] `README.md` exists with all required sections (Description, Getting
Started, Rationale, Design, TODO, License, Author)
- [ ] `LICENSE` file exists and matches the README
- [ ] `REPO_POLICIES.md` exists and version date is current — fetch from
- [ ] `docs/REPO_POLICIES.md` exists and version date is current — fetch from
`https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the
root — never a file or directory named after one agent tool, such as
@@ -49,32 +49,17 @@ with your task.
`--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
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 ./`,
`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
(`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
also mounts golangci-lint's
(`--mount=type=cache,target=/root/.cache/golangci-lint`), and no step
mounts anything else; both `go test` runs carry `-count=1`; a first run
that timed out gets no rerun, as in the canonical Go `Dockerfile` in
`REPO_POLICIES.md`
that timed out gets no rerun, as in `examples/go.Dockerfile` in the
`prompts` repo
- [ ] 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
`script/bootstrap` runs in that step, it installs nothing beyond these:
- system packages
@@ -91,9 +76,8 @@ with your task.
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
`python_version`, because `--deploy` stops when the distribution's Python
differs from it. The tests run after `ARG CACHEBUST`, and every other stage
installs its Python packages after it, as in the Python `test` phase example
in `REPO_POLICIES.md`
differs from it. The tests run after `COPY . .`, as in
`examples/python-test-phase.Dockerfile` in the `prompts` repo
- [ ] The gate phases invoke their tools directly, never through `make lint` or
`script/test` — those are themselves a `docker build` and would recurse
@@ -212,34 +196,25 @@ with your task.
- [ ] `script/precommit` exists and the pre-commit hook (installed by
`script/install-precommit`, shimmed by `make hooks`) runs it
- [ ] `script/update-policy` exists, identical to the model script, and
`make update-policy` shims to it. Before its first use, the repo's own
entries in `.gitignore`, `.editorconfig` and `.dockerignore` go below the
comment that ends each canonical file. An entry above that comment which
the canonical file has never held makes the script stop before it writes
anything, naming the file and the entry. It stops the same way on a line
in `.golangci.yml` that the canonical file has never held, apart from
comments and the repo's entries in the `deny` list of the `test-support`
rule.
`make update-policy` shims to it
- [ ] README has an **Entrypoints** section documenting the `script/`
entrypoints and linking the standard
- [ ] `script/lint` and `script/test` each run
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target <phase> --output type=cacheonly .`,
which builds their phase by name and writes no image, and no host
invocation anywhere in the repo can produce a lint verdict — grep for the
linter's own name across `script/`, the `Makefile` and CI config, not just
`script/lint`. A second path is likeliest here: a `make lint-fast`, an
older host-versus-container branch, or a CI step calling the binary
directly. `script/fmt` and `script/fmt-check` are expected hits and stay
on the host.
`docker build --target <phase> --output type=cacheonly .`, which builds
their phase by name and writes no image, and no host invocation anywhere
in the repo can produce a lint verdict — grep for the linter's own name
across `script/`, the `Makefile` and CI config, not just `script/lint`. A
second path is likeliest here: a `make lint-fast`, an older
host-versus-container branch, or a CI step calling the binary directly.
`script/fmt` and `script/fmt-check` are expected hits and stay on the
host.
- [ ] No `docker build` in `script/` leaves a dangling image behind:
`script/lint` and `script/test` write no image, and `script/docker` and
`script/cibuild` tag theirs. A build that writes an untagged image leaves
one behind on every run, on every host and CI runner.
- [ ] `script/cibuild` runs `script/bootstrap` before `script/check`, and builds
the image with a new `CACHEBUST` value on every build, like every
`docker build` in `script/`. Without the bootstrap the CI run dies in
`script/fmt-check`, which runs the formatter on the host and finds nothing
installed.
- [ ] `script/cibuild` runs `script/bootstrap` before `script/check`. Without
the bootstrap the CI run dies in `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
`yarn.lock` is in the tree. node and yarn come from the distribution when
they are missing. It installs the node packages with
@@ -327,14 +302,7 @@ with your task.
- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
That host is the runner image
`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
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`
node 24. Take any yarn off `PATH` first.
- [ ] A planted lint violation fails both `make lint` and a plain
`docker build .`; revert it afterwards
- [ ] Commit and merge fixes before starting your actual task
+23 -49
View File
@@ -1,6 +1,6 @@
---
title: New Repo Checklist
last_modified: 2026-11-09
last_modified: 2026-11-18
---
Use this checklist when creating a new repository from scratch. Follow the steps
@@ -55,7 +55,7 @@ Template files can be fetched from:
## Create Project Files
- [ ] `LICENSE` file matching the chosen license
- [ ] `REPO_POLICIES.md` — fetch from
- [ ] `docs/REPO_POLICIES.md` — fetch from
`https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the
root — never a file or directory named after one agent tool, such as
@@ -118,32 +118,17 @@ Template files can be fetched from:
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
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 ./`,
`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
(`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run`
also mounts golangci-lint's
(`--mount=type=cache,target=/root/.cache/golangci-lint`), and no step
mounts anything else; both `go test` runs carry `-count=1`; a first run
that timed out gets no rerun, as in the canonical Go `Dockerfile` in
`REPO_POLICIES.md`
that timed out gets no rerun, as in `examples/go.Dockerfile` in the
`prompts` repo
- 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
`script/bootstrap` runs in that step, it installs nothing beyond these:
- system packages
@@ -161,9 +146,8 @@ Template files can be fetched from:
for the image stops the install. In that step it installs no Python,
because a step above it already did. `Pipfile` names no
`python_version`, because `--deploy` stops when the distribution's
Python differs from it. The tests run after `ARG CACHEBUST`, and every
other stage installs its Python packages after it, as in the Python
`test` phase example in `REPO_POLICIES.md`
Python differs from it. The tests run after `COPY . .`, as in
`examples/python-test-phase.Dockerfile` in the `prompts` repo
- Server: the final stage builds and runs the application
- Non-server: the final stage brings up the dev environment
@@ -227,13 +211,12 @@ are thin shims calling them. Model scripts:
- [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
then `install-precommit`, plus repo-specific init
- [ ] `script/test` / `make test` —
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target test --output type=cacheonly .`,
which writes no image; the phase runs real tests, not a no-op (90-second
timeout, 60-second hard cap on wall time)
`docker build --target test --output type=cacheonly .`, which writes no
image; the phase runs real tests, not a no-op (90-second timeout,
60-second hard cap on wall time)
- [ ] `script/lint` / `make lint` —
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --target lint --output type=cacheonly .`,
which writes no image. No lint verdict may come from a host invocation of
the linter.
`docker build --target lint --output type=cacheonly .`, which writes no
image. No lint verdict may come from a host invocation of the linter.
- [ ] `script/fmt` / `make fmt` — formats code (writes; native, never in a
container). Go code gets `gofmt`, then `golines -m 77`.
- [ ] `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`
for the image tag)
- [ ] `script/docker` / `make docker` — builds Docker image, tagged via
`script/projectname` (byte-identical across repos); a new `CACHEBUST`
value on every build, plus the version as a build arg
`script/projectname` (byte-identical across repos), with the version as a
build arg
- [ ] `script/cibuild` — cd to repo root, run `script/bootstrap`, run
`script/check`, then
`docker build --build-arg CACHEBUST="$(date +%s)-$$" --build-arg VERSION="$version" -t "$tag" .`
(what CI runs), with `$version` from
`git describe --tags --always --dirty` (`unknown` if empty) and `$tag`
from `script/projectname`, each assigned on its own line before the build.
The bootstrap is required: CI checks out and runs this alone, and
`script/fmt-check` runs the formatter on the host.
`docker build --build-arg VERSION="$version" -t "$tag" .` (what CI runs),
with `$version` from `git describe --tags --always --dirty` (`unknown` if
empty) and `$tag` from `script/projectname`, each assigned on its own line
before the build. The bootstrap is required: CI checks out and runs this
alone, and `script/fmt-check` runs the formatter on the host.
- [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by
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
@@ -266,9 +248,8 @@ are thin shims calling them. Model scripts:
- [ ] `script/install-precommit` — installs the pre-commit hook that runs
`script/precommit`
- [ ] `make hooks` — shims to `script/install-precommit`
- [ ] `script/update-policy` / `make update-policy` — fetches the vendored
policy files from the `prompts` repo, commits them and pushes; identical
across repos
- [ ] `script/update-policy` / `make update-policy` — fetches the shared policy
files from the `prompts` repo and commits them; identical across repos
- [ ] README **Entrypoints** section documents the scripts and links the
standard
@@ -279,14 +260,7 @@ are thin shims calling them. Model scripts:
- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
That host is the runner image
`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
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`
node 24. Take any yarn off `PATH` first.
- [ ] 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
final stage is missing its `COPY --from=` edge to the gate phases.
+564 -812
View File
File diff suppressed because it is too large. Load diff
+1 -9
View File
@@ -2,12 +2,6 @@
# 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
# 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
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -25,9 +19,7 @@ main() {
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
[ -n "$version" ] || version="unknown"
tag="$("$SCRIPT_DIR/projectname")"
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--build-arg VERSION="$version" \
-t "$tag" .
docker build --build-arg VERSION="$version" -t "$tag" .
}
main "$@"
+1 -9
View File
@@ -1,12 +1,6 @@
#!/bin/sh
# script/docker: build the Docker image tagged with the project name.
# 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
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -22,9 +16,7 @@ main() {
version="$(git describe --tags --always --dirty 2>/dev/null || true)"
[ -n "$version" ] || version="unknown"
tag="$("$SCRIPT_DIR/projectname")"
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--build-arg VERSION="$version" \
-t "$tag" .
docker build --build-arg VERSION="$version" -t "$tag" .
}
main "$@"
+2 -2
View File
@@ -8,8 +8,8 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
main() {
cd "$ROOT"
hook=".git/hooks/pre-commit"
printf '#!/bin/sh\nset -e\nscript/precommit\n' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
printf '#!/bin/sh\nset -e\nscript/precommit\n' > "$hook"
chmod +x "$hook"
echo "pre-commit hook installed: runs script/precommit"
}
+4 -13
View File
@@ -1,18 +1,11 @@
#!/bin/sh
# 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
# make its answer untrustworthy.
#
# The phase is not the last stage in the file, so it is built only when
# --target names it. A new CACHEBUST value reruns every RUN step after
# 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.
# --target builds the lint phase and the stages it depends on, nothing
# else. --output type=cacheonly writes no image, since nothing uses one.
set -eu
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -20,9 +13,7 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
main() {
cd "$ROOT"
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--target lint \
--output type=cacheonly .
docker build --target lint --output type=cacheonly .
}
main "$@"
+5 -12
View File
@@ -1,14 +1,9 @@
#!/bin/sh
# 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:
# --target because a phase that is not the last stage is built only when
# named, and a new CACHEBUST value because a cached test layer is a test
# that did not run; unlike --no-cache, it keeps the layers above the ARG
# 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.
# and this builds that phase, on the same terms as script/lint:
# --target so that only the test phase and the stages it depends on are
# built, and --output type=cacheonly so that no image is written, since
# nothing uses one.
set -eu
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -16,9 +11,7 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
main() {
cd "$ROOT"
docker build --build-arg CACHEBUST="$(date +%s)-$$" \
--target test \
--output type=cacheonly .
docker build --target test --output type=cacheonly .
}
main "$@"
+37 -196
View File
@@ -1,43 +1,17 @@
#!/bin/sh
# script/update-policy: replace this repo's vendored policy files with
# the canonical ones from the prompts repo, commit them and push.
# Identical in all repos. Our own extension to
# scripts-to-rule-them-all.
#
# Usage: script/update-policy [full commit hash of prompts]
# Without a hash it uses the head of the prompts main branch.
#
# The script writes nothing until every file has been fetched and
# merged. A repo's own entries are kept:
# - .gitignore, .editorconfig, .dockerignore: the lines below the
# canonical file's last line. An entry above that line which the
# canonical file has never held stops the script.
# - .golangci.yml: the entries the repo added to the deny list of the
# test-support rule. Any other line the canonical file has never
# held stops the script, unless it is blank or a comment.
# script/update-policy: replace the files below with their current
# versions from the main branch of the prompts repo, and commit them. It
# does not push. Identical in all repos, and it updates itself.
set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
PROMPTS_URL="https://git.eeqj.de/sneak/prompts"
RAW_URL="https://git.eeqj.de/sneak/prompts/raw/branch/main"
# Paths in the prompts repo. A file this repo does not carry is skipped.
VENDORED_FILES="
.dockerignore
.editorconfig
.gitea/workflows/check.yml
.gitignore
.golangci.yml
.prettierrc
prompts/API_POLICIES.md
prompts/CODE_STYLEGUIDE.md
prompts/CODE_STYLEGUIDE_GO.md
prompts/CODE_STYLEGUIDE_JS.md
prompts/CODE_STYLEGUIDE_PYTHON.md
prompts/EXISTING_REPO_CHECKLIST.md
prompts/GO_HTTP_SERVER_CONVENTIONS.md
prompts/LLM_PROSE_TELLS.md
prompts/NEW_REPO_CHECKLIST.md
prompts/REPO_POLICIES.md
# Each entry is the path in prompts, a colon, then the path in this repo.
FILES="
prompts/REPO_POLICIES.md:docs/REPO_POLICIES.md
prompts/CODE_STYLEGUIDE.md:docs/CODE_STYLEGUIDE.md
script/update-policy:script/update-policy
"
die() {
@@ -45,178 +19,45 @@ die() {
exit 1
}
# local_path <path in prompts>: print where this repo keeps the file, or
# nothing if git does not track it here. A prompts/NAME.md lands at
# docs/NAME.md or NAME.md.
local_path() {
name="${1#prompts/}"
if [ "$name" != "$1" ] && [ -n "$(git ls-files -- "docs/$name")" ]; then
echo "docs/$name"
elif [ -n "$(git ls-files -- "$name")" ]; then
echo "$name"
fi
}
# local_only_lines <fetched> <local> [end]: print each line of the local
# file, above line end if given, that the canonical file has never held:
# not in the fetched file or in <fetched>.former, the lines earlier
# commits removed from it. Blank lines and comments do not count.
local_only_lines() {
cat "$1" "$1.former" | awk -v end="${3:-}" '
NR == FNR { held[$0]; next }
(end == "" || FNR < end) && !/^[ \t]*(#|$)/ && !($0 in held)
' - "$2"
}
# keep_lines_below_last <fetched> <local>: append to the fetched file
# whatever follows its last line in the local file. Stop if the canonical
# file has never held a line above that one, unless it is blank or a
# comment: replacing the file would delete it.
keep_lines_below_last() {
last="$(tail -n 1 "$1")"
number="$(grep -n -F -x -- "$last" "$2" | head -n 1 | cut -d: -f1)"
if [ -z "$last" ] || [ -z "$number" ]; then
die "$2 lacks this line; add it and put the repo's own entries below it: $last"
fi
own="$(local_only_lines "$1" "$2" "$number")"
if [ -n "$own" ]; then
die "$2 has entries above its last canonical line that the canonical file lacks; move each below that line to keep it, or delete it:
$own"
fi
tail -n "+$((number + 1))" "$2" >> "$1"
}
# keep_deny_entries <fetched> <local>: add to the deny list of the
# test-support rule in the fetched file the entries only the local file
# has. An entry is a "- pkg:" line, the lines under it and any comment
# above it. Stop if the local file still has a line that neither the
# result nor the canonical file has ever held, unless it is blank or a
# comment: replacing the file would delete it.
keep_deny_entries() {
awk '
function indent(line) { return match(line, /[^ ]/) - 1 }
function print_local_entries(i) {
for (i = 1; i <= count; i++)
if (!(pkg[i] in fetched_pkg))
printf "%s", entry[i]
}
FNR == 1 { in_rule = 0; in_list = 0 }
in_list && /[^ ]/ && indent($0) <= list_indent {
in_list = 0
if (FILENAME == ARGV[2]) print_local_entries()
}
in_list {
is_entry = ($1 == "-" && $2 == "pkg:")
if (FILENAME == ARGV[2]) {
if (is_entry) fetched_pkg[$3]
print
} else if (is_entry) {
count++
pkg[count] = $3
entry[count] = comment $0 "\n"
comment = ""
} else if (/^ *#/) {
comment = comment $0 "\n"
} else if (count) {
entry[count] = entry[count] $0 "\n"
}
next
}
in_rule && /^ *[^ #]/ && indent($0) <= rule_indent { in_rule = 0 }
/^ *test-support:/ { in_rule = 1; rule_indent = indent($0) }
in_rule && /^ *deny:/ {
in_rule = 0
in_list = 1
list_indent = indent($0)
if (FILENAME == ARGV[2]) found = 1
}
FILENAME == ARGV[2] { print }
END {
if (in_list) print_local_entries()
exit !found
}
' "$2" "$1" > "$1.merged" ||
die "the fetched $2 has no deny list in its test-support rule"
mv "$1.merged" "$1"
own="$(local_only_lines "$1" "$2")"
if [ -n "$own" ]; then
die "$2 has lines the canonical file has never held; only the deny list of the test-support rule may differ from canonical:
$own"
fi
}
main() {
cd "$ROOT"
[ ! -e prompts/REPO_POLICIES.md ] ||
die "this is the prompts repo, where these files come from"
[ ! -e REPO_POLICIES.md ] ||
die "REPO_POLICIES.md is at the root;" \
"move it into docs/ with git mv and fix the links to it first"
[ "$#" -le 1 ] || die "usage: script/update-policy [full commit hash]"
paths=""
for entry in $FILES; do
paths="$paths ${entry#*:}"
done
[ -z "$(git status --porcelain -- $paths)" ] ||
die "commit or discard your changes to these files first:$paths"
project="$(script/projectname)"
if [ "$project" = "prompts" ]; then
die "this repo is the source of the policy files"
fi
commit="${1:-}"
if [ -z "$commit" ]; then
head_line="$(git ls-remote "$PROMPTS_URL.git" refs/heads/main)"
commit="${head_line%%[[:space:]]*}"
fi
printf '%s\n' "$commit" | grep -Eqx '[0-9a-f]{40}' ||
die "not a full commit hash: '$commit'"
tmp="$(mktemp -d)"
# Every file is fetched before any is replaced. The temporary
# directory is inside the repo so that mv renames: the running script
# is replaced by a new file, never rewritten in place.
tmp="$(mktemp -d "$ROOT/.update-policy.XXXXXX")"
trap 'rm -rf "$tmp"' EXIT
git clone --quiet --bare "$PROMPTS_URL.git" "$tmp/prompts.git" ||
die "cannot clone $PROMPTS_URL.git"
carried=""
for file in $VENDORED_FILES; do
path="$(local_path "$file")"
[ -n "$path" ] || continue
if [ -n "$(git status --porcelain -- "$path")" ]; then
die "$path has uncommitted changes"
fi
mkdir -p "$tmp/$(dirname "$path")"
curl --fail --silent --show-error --max-time 60 \
--output "$tmp/$path" \
"$PROMPTS_URL/raw/commit/$commit/$file" ||
die "cannot fetch $file at $commit"
git -C "$tmp/prompts.git" log -p --format= "$commit" -- "$file" |
sed -n 's/^-//p' > "$tmp/$path.former"
carried="$carried $path"
for entry in $FILES; do
mkdir -p "$tmp/$(dirname "${entry#*:}")"
wget -q -T 60 -O "$tmp/${entry#*:}" "$RAW_URL/${entry%%:*}" ||
die "cannot fetch $RAW_URL/${entry%%:*}"
done
[ -n "$carried" ] || die "this repo carries none of the vendored files"
chmod 755 "$tmp/script/update-policy"
for path in $carried; do
case "$path" in
.gitignore | .editorconfig | .dockerignore)
keep_lines_below_last "$tmp/$path" "$path"
;;
.golangci.yml)
keep_deny_entries "$tmp/$path" "$path"
;;
esac
for path in $paths; do
mkdir -p "$(dirname "$path")"
mv "$tmp/$path" "$path"
done
for path in $carried; do
cp "$tmp/$path" "$path"
git add -- "$path"
done
if git diff --cached --quiet -- $carried; then
echo "update-policy: already at prompts $commit, nothing to commit"
git add -- $paths
if git diff --cached --quiet -- $paths; then
echo "update-policy: already current, nothing to commit"
else
git commit -m "Update policy files from prompts $commit" -- $carried
git commit -q -m "Update policy files from prompts" -- $paths
echo "update-policy: committed; review it, then push"
fi
# Also pushes when there was nothing to commit, so a run after a
# failed push delivers the commit that push left behind.
git push origin HEAD || die "push failed; fix that and run this again"
}
main "$@"
+74 -539
View File
@@ -1,14 +1,14 @@
#!/bin/sh
# test/update-policy.sh: test script/update-policy on throwaway repos.
# Each scenario gets one temp directory holding a repo, its local bare
# origin, a local git repository of the canonical files in place of
# prompts, and a stub curl that serves them, so nothing touches the
# network.
# test/update-policy.sh: test script/update-policy on throwaway repos. A
# stub wget serves the files from this checkout, or fails for the path
# in WGET_FAIL, so nothing touches the network. Like wget, it writes a
# new file without the execute bit, whatever the source's mode.
set -eu
UPDATE_POLICY="$(cd "$(dirname "$0")/.." && pwd -P)/script/update-policy"
PROMPTS="$(cd "$(dirname "$0")/.." && pwd -P)"
LISTED="docs/REPO_POLICIES.md docs/CODE_STYLEGUIDE.md script/update-policy"
dir=""
dir="$(mktemp -d)"
trap 'rm -rf "$dir"' EXIT
fail() {
@@ -17,551 +17,86 @@ fail() {
exit 1
}
write_stub_curl() {
mkdir "$dir/bin"
cat > "$dir/bin/curl" << 'EOF'
cat > "$dir/bin/wget" << EOF
#!/bin/sh
previous=""
fail_flag=""
for argument in "$@"; do
[ "$previous" = "--output" ] && output="$argument"
[ "$argument" = "--fail" ] && fail_flag=yes
previous="$argument"
while [ "\$#" -gt 1 ]; do
[ "\$1" = "-O" ] && output="\$2"
shift
done
url="$previous"
base="https://git.eeqj.de/sneak/prompts/raw/commit/$HASH/"
path="${url#"$base"}"
source="$(dirname "$0")/../canonical/$path"
if [ "$path" = "$url" ] || [ ! -f "$source" ]; then
[ -n "$fail_flag" ] && exit 22
echo "404 page not found" > "$output"
exit 0
fi
cp "$source" "$output"
path="\${1#https://git.eeqj.de/sneak/prompts/raw/branch/main/}"
[ "\$path" != "\${WGET_FAIL:-}" ] || exit 1
cat "$PROMPTS/\$path" > "\$output"
EOF
chmod +x "$dir/bin/curl"
}
chmod +x "$dir/bin/wget"
PATH="$dir/bin:$PATH"
export PATH
write_canonical_files() {
mkdir -p "$dir/canonical/prompts"
cat > "$dir/canonical/.gitignore" << 'EOF'
*.log
*.tmp
# Own entries go below this comment.
EOF
cat > "$dir/canonical/.dockerignore" << 'EOF'
**/*.log
**/*.tmp
# Own entries go below this comment.
EOF
cat > "$dir/canonical/.editorconfig" << 'EOF'
root = true
[*]
indent_size = 4
# Own sections go below this comment.
EOF
cat > "$dir/canonical/.golangci.yml" << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
deny:
- pkg: net/http/httptest
desc: canonical
- pkg: net/http/cgi
desc: added canonically
other:
deny:
- pkg: example.com/other
EOF
echo '{ "tabWidth": 4 }' > "$dir/canonical/.prettierrc"
echo "new policy" > "$dir/canonical/prompts/REPO_POLICIES.md"
echo "new api policy" > "$dir/canonical/prompts/API_POLICIES.md"
}
# commit_canonical: commit the canonical files as they stand. The stub
# curl serves only the newest commit; every other commit gets a 404.
commit_canonical() {
git -C "$dir/canonical" add .gitignore .dockerignore .editorconfig \
.golangci.yml .prettierrc prompts
git -C "$dir/canonical" commit -q -m "Canonical"
HASH="$(git -C "$dir/canonical" rev-parse HEAD)"
}
# write_outdated_files: this repo's files, one canonical version behind,
# with the repo's own entries in the places the script keeps them. The
# comment above the closing comment in .gitignore is replaced, not kept.
write_outdated_files() {
cat > "$dir/repo/.gitignore" << 'EOF'
*.log
# An outdated comment.
# Own entries go below this comment.
/myapp
EOF
cat > "$dir/repo/.dockerignore" << 'EOF'
**/*.log
# Own entries go below this comment.
/myapp
EOF
cat > "$dir/repo/.editorconfig" << 'EOF'
root = true
[*]
# Own sections go below this comment.
[*.py]
indent_size = 2
EOF
cat > "$dir/repo/.golangci.yml" << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
deny:
- pkg: net/http/httptest
desc: canonical
# Our own test helpers.
- pkg: example.com/app/internal/apptest
desc: own entry
other:
deny:
- pkg: example.com/other
EOF
echo '{ "tabWidth": 2 }' > "$dir/repo/.prettierrc"
echo "old policy" > "$dir/repo/REPO_POLICIES.md"
}
# start_scenario <name>: make a new temp directory holding a repo with
# the outdated files, not yet committed, and an empty origin.
start_scenario() {
# new_repo: a repo with one commit, holding only an older copy of the
# script that is shorter than the new one. A run that rewrote the running
# script in place, instead of replacing it, would then read the new
# file's last lines as commands and fail.
new_repo() {
scenario="$1"
rm -rf "$dir"
dir="$(mktemp -d)"
: > "$dir/output"
write_stub_curl
write_canonical_files
# git clone reads no repo's own config, so the setting that points
# git at the local canonical repository has to be in this file.
export GIT_CONFIG_GLOBAL="$dir/gitconfig"
git config --global user.name "Test"
git config --global user.email "test@example.com"
git config --global "url.$dir/canonical.insteadOf" \
"https://git.eeqj.de/sneak/prompts.git"
git init -q -b main "$dir/canonical"
export HASH
commit_canonical
git init -q --bare -b main "$dir/origin.git"
git init -q -b main "$dir/repo"
git -C "$dir/repo" remote add origin "$dir/origin.git"
mkdir "$dir/repo/script"
cp "$UPDATE_POLICY" "$dir/repo/script/update-policy"
printf '#!/bin/sh\necho example\n' > "$dir/repo/script/projectname"
chmod +x "$dir/repo/script/projectname"
write_outdated_files
}
# commit_and_push_fixture <paths...>: commit those paths, remove the
# rest of the outdated files, and record the commit as $before.
commit_and_push_fixture() {
(
rm -rf "$dir/repo"
git init -q "$dir/repo"
cd "$dir/repo"
git add script "$@"
git commit -q -m "Fixture"
git push -q origin HEAD
git clean -q -f -x
)
before="$(git -C "$dir/repo" rev-parse HEAD)"
git config user.name test
git config user.email test@example.com
mkdir script
grep -v '^# ' "$PROMPTS/script/update-policy" > script/update-policy
chmod +x script/update-policy
echo own > README.md
git add README.md script/update-policy
git commit -q -m initial
}
run_update_policy() {
status=0
(cd "$dir/repo" && PATH="$dir/bin:$PATH" script/update-policy "$@") \
> "$dir/output" 2>&1 || status=$?
}
new_repo "a first run writes and commits exactly the listed files"
echo stray > stray.txt
echo staged >> README.md
git add README.md
script/update-policy > "$dir/output" 2>&1 || fail "exited non-zero"
[ "$(git rev-list --count HEAD)" = 2 ] || fail "made no single commit"
[ "$(git show --name-only --format= HEAD | sort)" = \
"$(echo "$LISTED" | tr ' ' '\n' | sort)" ] || fail "commit holds other files"
cmp -s docs/REPO_POLICIES.md "$PROMPTS/prompts/REPO_POLICIES.md" ||
fail "REPO_POLICIES.md differs"
[ -x script/update-policy ] || fail "script not executable"
[ "$(git status --porcelain)" = "$(printf 'M README.md\n?? stray.txt')" ] ||
fail "changed files outside the list"
reject_pushes() {
printf '#!/bin/sh\nexit 1\n' > "$dir/origin.git/hooks/pre-receive"
chmod +x "$dir/origin.git/hooks/pre-receive"
}
scenario="a second run commits nothing"
script/update-policy > "$dir/output" 2>&1 || fail "exited non-zero"
[ "$(git rev-list --count HEAD)" = 2 ] || fail "made a commit"
grep -q "nothing to commit" "$dir/output" || fail "did not say so"
accept_pushes() {
rm "$dir/origin.git/hooks/pre-receive"
}
new_repo "a failed fetch writes nothing"
WGET_FAIL=prompts/CODE_STYLEGUIDE.md script/update-policy > "$dir/output" 2>&1 &&
fail "exited zero"
grep -q "cannot fetch" "$dir/output" || fail "did not say cannot fetch"
[ ! -e docs ] || fail "wrote docs/"
[ -z "$(git status --porcelain)" ] || fail "tree changed"
head_of_repo() {
git -C "$dir/repo" rev-parse HEAD
}
new_repo "an uncommitted change to a listed file stops the script"
mkdir docs
echo mine > docs/REPO_POLICIES.md
script/update-policy > "$dir/output" 2>&1 && fail "exited zero"
[ "$(cat docs/REPO_POLICIES.md)" = mine ] || fail "overwrote the change"
head_of_origin() {
git -C "$dir/origin.git" rev-parse refs/heads/main
}
new_repo "a REPO_POLICIES.md at the root stops the script"
echo old > REPO_POLICIES.md
git add REPO_POLICIES.md
git commit -q -m "root policy file"
script/update-policy > "$dir/output" 2>&1 && fail "exited zero"
grep -q "git mv" "$dir/output" || fail "did not say to move it"
[ ! -e docs ] || fail "wrote docs/"
[ -z "$(git status --porcelain)" ] || fail "tree changed"
[ "$(git rev-list --count HEAD)" = 2 ] || fail "made a commit"
expect_success() {
[ "$status" -eq 0 ] || fail "exited $status"
}
new_repo "the prompts repo itself is refused"
mkdir prompts
echo source > prompts/REPO_POLICIES.md
script/update-policy > "$dir/output" 2>&1 && fail "exited zero"
[ ! -e docs ] || fail "wrote docs/"
expect_failure() {
[ "$status" -ne 0 ] || fail "exited 0"
}
expect_output() {
grep -q -F -e "$1" "$dir/output" || fail "output lacks: $1"
}
expect_output_without() {
if grep -q -F -e "$1" "$dir/output"; then
fail "output has: $1"
fi
}
# expect_file <path>: the file must equal standard input.
expect_file() {
cat > "$dir/expected"
diff "$dir/expected" "$dir/repo/$1" >&2 || fail "$1 is wrong"
}
expect_absent() {
[ ! -e "$dir/repo/$1" ] || fail "$1 exists"
}
expect_nothing_written() {
[ -z "$(git -C "$dir/repo" status --porcelain)" ] ||
fail "the working tree changed"
[ "$(head_of_repo)" = "$before" ] || fail "the repo has a new commit"
[ "$(head_of_origin)" = "$before" ] || fail "origin has a new commit"
}
test_own_entries_kept() {
start_scenario "own entries kept in all four files"
commit_and_push_fixture .gitignore .dockerignore .editorconfig \
.golangci.yml .prettierrc REPO_POLICIES.md
run_update_policy "$HASH"
expect_success
expect_file .gitignore << 'EOF'
*.log
*.tmp
# Own entries go below this comment.
/myapp
EOF
expect_file .dockerignore << 'EOF'
**/*.log
**/*.tmp
# Own entries go below this comment.
/myapp
EOF
expect_file .editorconfig << 'EOF'
root = true
[*]
indent_size = 4
# Own sections go below this comment.
[*.py]
indent_size = 2
EOF
expect_file .golangci.yml << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
deny:
- pkg: net/http/httptest
desc: canonical
- pkg: net/http/cgi
desc: added canonically
# Our own test helpers.
- pkg: example.com/app/internal/apptest
desc: own entry
other:
deny:
- pkg: example.com/other
EOF
expect_file .prettierrc << 'EOF'
{ "tabWidth": 4 }
EOF
expect_file REPO_POLICIES.md << 'EOF'
new policy
EOF
[ "$(head_of_origin)" = "$(head_of_repo)" ] ||
fail "the commit was not pushed"
[ "$(head_of_repo)" != "$before" ] || fail "no commit was made"
git -C "$dir/repo" log -1 --format=%s | grep -q -F -e "$HASH" ||
fail "the commit message does not name the hash"
}
test_files_not_carried_are_skipped() {
start_scenario "files the repo does not carry skipped"
mkdir "$dir/repo/docs"
mv "$dir/repo/REPO_POLICIES.md" "$dir/repo/docs/REPO_POLICIES.md"
commit_and_push_fixture docs/REPO_POLICIES.md
run_update_policy "$HASH"
expect_success
expect_file docs/REPO_POLICIES.md << 'EOF'
new policy
EOF
expect_absent REPO_POLICIES.md
expect_absent API_POLICIES.md
expect_absent docs/API_POLICIES.md
expect_absent .gitignore
expect_absent .dockerignore
expect_absent .editorconfig
expect_absent .golangci.yml
expect_absent .prettierrc
[ "$(head_of_origin)" = "$(head_of_repo)" ] ||
fail "the commit was not pushed"
}
test_nothing_changed() {
start_scenario "nothing changed"
cp "$dir/canonical/.prettierrc" "$dir/repo/.prettierrc"
commit_and_push_fixture .prettierrc
run_update_policy "$HASH"
expect_success
expect_output "nothing to commit"
expect_nothing_written
}
test_bad_commit_hash() {
for hash in not-a-hash 0000000000000000000000000000000000000000; do
start_scenario "bad commit hash $hash stops with nothing written"
commit_and_push_fixture .gitignore .prettierrc REPO_POLICIES.md
run_update_policy "$hash"
expect_failure
expect_nothing_written
done
# The last hash has the right form, so it is the one that reaches curl.
expect_output "cannot fetch"
}
test_push_failure() {
start_scenario "push failure exits non-zero"
commit_and_push_fixture .prettierrc
reject_pushes
run_update_policy "$HASH"
expect_failure
expect_output "push failed"
[ "$(head_of_origin)" = "$before" ] || fail "origin has a new commit"
}
# Each of these files, with the repo's own entries above the closing
# comment. The comment added with them must not be named.
test_own_entry_above_closing_comment() {
for file in .gitignore .dockerignore .editorconfig; do
start_scenario "own entries above the closing comment of $file stop"
{
printf '/myapp\n/.tool/\n\n# A comment of our own.\n'
cat "$dir/repo/$file"
} > "$dir/merged"
mv "$dir/merged" "$dir/repo/$file"
commit_and_push_fixture .gitignore .dockerignore .editorconfig \
.prettierrc REPO_POLICIES.md
run_update_policy "$HASH"
expect_failure
expect_output "$file has entries"
expect_output "/myapp"
expect_output "/.tool/"
expect_output_without "A comment of our own."
expect_nothing_written
done
}
test_retry_after_failed_push() {
start_scenario "a retry after a failed push delivers the commit"
commit_and_push_fixture .prettierrc
reject_pushes
run_update_policy "$HASH"
expect_failure
committed="$(head_of_repo)"
[ "$committed" != "$before" ] || fail "no commit was made"
[ "$(head_of_origin)" = "$before" ] || fail "origin has a new commit"
accept_pushes
run_update_policy "$HASH"
expect_success
[ "$(head_of_repo)" = "$committed" ] || fail "the retry made a new commit"
[ "$(head_of_origin)" = "$committed" ] ||
fail "the retry did not deliver the commit"
}
test_uncommitted_change_stops() {
start_scenario "a carried file with uncommitted changes stops"
commit_and_push_fixture .prettierrc REPO_POLICIES.md
echo "uncommitted" >> "$dir/repo/REPO_POLICIES.md"
run_update_policy "$HASH"
expect_failure
expect_output "REPO_POLICIES.md has uncommitted changes"
expect_file REPO_POLICIES.md << 'EOF'
old policy
uncommitted
EOF
[ "$(head_of_repo)" = "$before" ] || fail "the repo has a new commit"
[ "$(head_of_origin)" = "$before" ] || fail "origin has a new commit"
}
test_gitignore_lacks_canonical_last_line() {
start_scenario ".gitignore lacking the canonical last line stops"
printf '*.log\n/myapp\n' > "$dir/repo/.gitignore"
commit_and_push_fixture .gitignore .prettierrc
run_update_policy "$HASH"
expect_failure
expect_output ".gitignore lacks this line"
expect_nothing_written
}
test_fetched_golangci_without_deny_list() {
start_scenario "a fetched .golangci.yml with no deny list stops"
cat > "$dir/canonical/.golangci.yml" << 'EOF'
linters:
settings:
depguard:
rules:
test-support:
files:
- "**/*.go"
other:
deny:
- pkg: example.com/other
EOF
commit_and_push_fixture .golangci.yml .prettierrc
run_update_policy "$HASH"
expect_failure
expect_output "no deny list in its test-support rule"
expect_nothing_written
}
test_own_golangci_setting_stops() {
start_scenario "a .golangci.yml setting the canonical file lacks stops"
cat >> "$dir/repo/.golangci.yml" << 'EOF'
# A comment of our own.
forbidigo:
forbid:
- pattern: model.Operator
EOF
commit_and_push_fixture .golangci.yml .prettierrc
run_update_policy "$HASH"
expect_failure
expect_output ".golangci.yml has lines"
expect_output "forbidigo:"
expect_output "- pattern: model.Operator"
expect_output_without "A comment of our own."
expect_nothing_written
}
test_source_repo_stops() {
start_scenario "the repo the policy files come from stops"
printf '#!/bin/sh\necho prompts\n' > "$dir/repo/script/projectname"
commit_and_push_fixture .prettierrc REPO_POLICIES.md
run_update_policy "$HASH"
expect_failure
expect_output "this repo is the source of the policy files"
expect_nothing_written
}
test_staged_file_stays_out_of_commit() {
start_scenario "a file staged before the script starts stays out of its commit"
commit_and_push_fixture .prettierrc
echo "notes" > "$dir/repo/notes.txt"
git -C "$dir/repo" add notes.txt
run_update_policy "$HASH"
expect_success
[ "$(git -C "$dir/repo" show --name-only --format= HEAD)" = ".prettierrc" ] ||
fail "the commit holds more than the policy file"
[ "$(git -C "$dir/repo" diff --cached --name-only)" = "notes.txt" ] ||
fail "notes.txt is no longer staged"
}
test_short_commit_hash_refused() {
start_scenario "a hexadecimal hash shorter than 40 characters is refused"
commit_and_push_fixture .prettierrc
run_update_policy "${HASH%?}"
expect_failure
expect_output "not a full commit hash"
expect_nothing_written
}
# git asks the local canonical repository for the head of main, and the
# stub curl serves only that commit.
test_no_hash_uses_head_of_main() {
start_scenario "with no hash the script uses the head of main"
commit_and_push_fixture .prettierrc
run_update_policy
expect_success
expect_file .prettierrc << 'EOF'
{ "tabWidth": 4 }
EOF
git -C "$dir/repo" log -1 --format=%s | grep -q -F -e "$HASH" ||
fail "the commit message does not name the head of main"
[ "$(head_of_origin)" = "$(head_of_repo)" ] ||
fail "the commit was not pushed"
}
# expect_former_canonical_line_replaced <file> <line>: an earlier
# canonical commit held the line and the newest does not. This repo's
# file still has it, and the script replaces it and pushes.
expect_former_canonical_line_replaced() {
cp "$dir/canonical/$1" "$dir/newest"
{ echo "$2"; cat "$dir/newest"; } > "$dir/canonical/$1"
commit_canonical
cp "$dir/newest" "$dir/canonical/$1"
commit_canonical
{ echo "$2"; cat "$dir/repo/$1"; } > "$dir/merged"
mv "$dir/merged" "$dir/repo/$1"
commit_and_push_fixture "$1" .prettierrc
run_update_policy "$HASH"
expect_success
if grep -q -F -x -e "$2" "$dir/repo/$1"; then
fail "$1 still has: $2"
fi
[ "$(head_of_repo)" != "$before" ] || fail "no commit was made"
[ "$(head_of_origin)" = "$(head_of_repo)" ] ||
fail "the commit was not pushed"
}
test_former_canonical_golangci_line_replaced() {
start_scenario "a .golangci.yml line an earlier canonical commit held is replaced"
expect_former_canonical_line_replaced .golangci.yml "version: 1"
}
test_former_canonical_gitignore_line_replaced() {
start_scenario "a .gitignore line above the closing comment that an earlier canonical commit held is replaced"
expect_former_canonical_line_replaced .gitignore "*.old"
}
main() {
test_own_entries_kept
test_files_not_carried_are_skipped
test_nothing_changed
test_bad_commit_hash
test_push_failure
test_own_entry_above_closing_comment
test_retry_after_failed_push
test_uncommitted_change_stops
test_gitignore_lacks_canonical_last_line
test_fetched_golangci_without_deny_list
test_own_golangci_setting_stops
test_source_repo_stops
test_staged_file_stays_out_of_commit
test_short_commit_hash_refused
test_no_hash_uses_head_of_main
test_former_canonical_golangci_line_replaced
test_former_canonical_gitignore_line_replaced
echo "update-policy tests passed"
}
main "$@"