Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 sneak
|
b910a1e808 |
+10
-22
@@ -3,9 +3,6 @@ version: "2"
|
||||
# Config schema uses the golangci-lint v2 layout (settings live under
|
||||
# linters.settings, not top-level linters-settings) so that the
|
||||
# thresholds below are actually applied by golangci-lint >= v2.
|
||||
#
|
||||
# This file has no formatters section, so golangci-lint run does not run
|
||||
# gofmt. A repository's script/fmt-check runs it, on the host.
|
||||
|
||||
run:
|
||||
timeout: 5m
|
||||
@@ -19,13 +16,13 @@ linters:
|
||||
- gomodguard_v2
|
||||
disable:
|
||||
# Genuinely incompatible with project patterns
|
||||
- exhaustruct_v5 # Requires all struct fields
|
||||
- exhaustruct # Requires all struct fields
|
||||
- exhaustruct_v5 # Requires all struct fields (successor to exhaustruct)
|
||||
- godot # Requires comments to end with periods
|
||||
- wrapcheck # Too verbose for internal packages
|
||||
- varnamelen # Short names like db, id are idiomatic Go
|
||||
# Deprecated: the warning is attached to the old name, so it is
|
||||
# silenced by disabling that name, not by enabling the successor.
|
||||
- exhaustruct # Deprecated, replaced by exhaustruct_v5
|
||||
- wsl # Deprecated, replaced by wsl_v5
|
||||
- gomodguard # Deprecated, replaced by gomodguard_v2
|
||||
settings:
|
||||
@@ -43,10 +40,7 @@ linters:
|
||||
# test-support package exists to hand a test privileges the program
|
||||
# itself must never have, so a file that is not a test must not import
|
||||
# one. Test files, and the files inside a package whose directory name
|
||||
# ends in `test`, are where that code belongs, and are exempt. A package
|
||||
# in a subdirectory of that directory is not exempt. `${base-path}` is
|
||||
# the directory holding this file, so the name of the directory a
|
||||
# repository is cloned into does not count.
|
||||
# ends in `test`, are where that code belongs, and are exempt.
|
||||
#
|
||||
# The deny list below is the one part of this file a repository is
|
||||
# expected to extend, and the only part it may. depguard matches an
|
||||
@@ -61,25 +55,24 @@ linters:
|
||||
files:
|
||||
- "$all"
|
||||
- "!$test"
|
||||
- "!${base-path}**/*test/*"
|
||||
- "!**/*test/**"
|
||||
deny:
|
||||
- pkg: net/http/httptest
|
||||
desc: >-
|
||||
Test-support code belongs in test files and in packages whose
|
||||
directory name ends in test, not in the shipped binary.
|
||||
# Each entry names a module not to use and what to use instead. Every
|
||||
# entry matches the module path exactly.
|
||||
# Only decisions already recorded in the Go package defaults are
|
||||
# listed here. Every entry matches the module path exactly.
|
||||
gomodguard_v2:
|
||||
blocked:
|
||||
- module: github.com/rs/zerolog
|
||||
recommendations:
|
||||
- log/slog
|
||||
reason: "Structured logging is stdlib log/slog."
|
||||
# These entries cover only the github.com/go-redis/redis module paths,
|
||||
# one entry per path, because the later releases are separate paths.
|
||||
# A prefix match would be shorter but would also reach
|
||||
# github.com/go-redis/redismock/v9, the test double for the successor
|
||||
# these entries recommend.
|
||||
# One entry per pre-fork module path, because the later releases
|
||||
# are separate paths. A prefix match would be shorter but would
|
||||
# also reach github.com/go-redis/redismock, the test double for
|
||||
# the successor these entries recommend.
|
||||
- module: github.com/go-redis/redis
|
||||
recommendations:
|
||||
- github.com/redis/go-redis/v9
|
||||
@@ -92,10 +85,6 @@ linters:
|
||||
recommendations:
|
||||
- github.com/redis/go-redis/v9
|
||||
reason: "Pre-fork module; use the maintained go-redis v9."
|
||||
- module: github.com/go-redis/redis/v9
|
||||
recommendations:
|
||||
- github.com/redis/go-redis/v9
|
||||
reason: "Pre-fork module; use the maintained go-redis v9."
|
||||
- module: github.com/sergi/go-diff
|
||||
recommendations:
|
||||
- github.com/aymanbagabas/go-udiff
|
||||
@@ -119,4 +108,3 @@ linters:
|
||||
issues:
|
||||
max-issues-per-linter: 0
|
||||
max-same-issues: 0
|
||||
uniq-by-line: false
|
||||
|
||||
@@ -21,46 +21,15 @@ fmt-check, and commit.
|
||||
|
||||
# Completed Steps
|
||||
|
||||
- 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-11-01: Moved the canonical golangci-lint to v2.15.0 (released
|
||||
2026-10-16), still built with go1.27.0, so the `go` directive rule is
|
||||
unchanged. The canonical `.golangci.yml` passes `golangci-lint config verify`
|
||||
on v2.15.0, and `default: all` switches on no new linter. `canonicalheader` is
|
||||
enabled again (issue 105): v2.15.0 carries the upstream commit "fix:
|
||||
non-deterministic results", and on a scratch package with two planted findings
|
||||
beside a `ResponseWriter.Header()` call, linted 20 times with each pinned
|
||||
image, v2.14.0 reported them on 8 runs and nothing on 12, while v2.15.0
|
||||
reported them on all 20.
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Existing Repo Checklist
|
||||
last_modified: 2026-11-03
|
||||
last_modified: 2026-10-26
|
||||
---
|
||||
|
||||
Use this checklist when beginning work in a repo that may not yet conform to our
|
||||
@@ -70,9 +70,8 @@ with your task.
|
||||
(`--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`
|
||||
mounts anything else; both `go test` runs carry `-count=1`, as in the
|
||||
canonical Go `Dockerfile` in `REPO_POLICIES.md`
|
||||
- [ ] Python: a `test` phase that installs its packages from `Pipfile.lock` does
|
||||
it above `ARG CACHEBUST`, with `COPY script/ script/`,
|
||||
`COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
|
||||
@@ -216,12 +215,7 @@ with your task.
|
||||
- [ ] Pre-commit hook is installed (`make hooks`)
|
||||
- [ ] No secrets in the repo (`.env`, keys, credentials)
|
||||
- [ ] No mutable references in Dockerfiles or scripts (tags, `@latest`) — all
|
||||
pinned by cryptographic hash with version/date comment. The one exception
|
||||
is a package from the distribution's own package index, which needs no
|
||||
version and no hash. Pulling that index is also allowed. In a
|
||||
`Dockerfile`, the distribution is the pinned base image's. On a host, it
|
||||
is the host's. A package source that a `Dockerfile` adds itself does not
|
||||
get this exception
|
||||
pinned by cryptographic hash with version/date comment
|
||||
- [ ] Using `yarn`, not `npm` (JS projects)
|
||||
|
||||
# Directory Structure
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: New Repo Checklist
|
||||
last_modified: 2026-11-03
|
||||
last_modified: 2026-10-26
|
||||
---
|
||||
|
||||
Use this checklist when creating a new repository from scratch. Follow the steps
|
||||
@@ -129,9 +129,8 @@ Template files can be fetched from:
|
||||
(`--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`
|
||||
mounts anything else; both `go test` runs carry `-count=1`, as in the
|
||||
canonical Go `Dockerfile` in `REPO_POLICIES.md`
|
||||
- Python: a `test` phase that installs its packages from `Pipfile.lock` does
|
||||
it above `ARG CACHEBUST`, with `COPY script/ script/`,
|
||||
`COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
|
||||
@@ -243,11 +242,7 @@ are thin shims calling them. Model scripts:
|
||||
final stage is missing its `COPY --from=` edge to the gate phases.
|
||||
- [ ] No secrets in repo, and none in the build context: enumerate a probe image
|
||||
rather than reading `.dockerignore`
|
||||
- [ ] No mutable image/package references. The one exception is a package from
|
||||
the distribution's own package index, which needs no version and no hash.
|
||||
Pulling that index is also allowed. In a `Dockerfile`, the distribution is
|
||||
the pinned base image's. On a host, it is the host's. A package source
|
||||
that a `Dockerfile` adds itself does not get this exception
|
||||
- [ ] No mutable image/package references
|
||||
- [ ] No unnecessary files in repo root
|
||||
- [ ] All dates written as YYYY-MM-DD
|
||||
|
||||
|
||||
+34
-92
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Repository Policies
|
||||
last_modified: 2026-11-03
|
||||
last_modified: 2026-11-01
|
||||
---
|
||||
|
||||
This document covers repository structure, tooling, and workflow standards. Code
|
||||
@@ -20,36 +20,19 @@ style conventions are in separate documents:
|
||||
`last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync
|
||||
with the authoritative source as policies evolve.
|
||||
|
||||
- **External references must be pinned by cryptographic hash.** This includes
|
||||
Docker base images, Go modules, npm packages, GitHub Actions, and anything
|
||||
else fetched from a remote source. Version tags (`@v4`, `@latest`, `:3.21`,
|
||||
etc.) are server-mutable and therefore remote code execution vulnerabilities.
|
||||
Reference an external dependency by its content hash (Docker `@sha256:...`, Go
|
||||
module hash in `go.sum`, npm integrity hash in lockfile, GitHub Actions
|
||||
`@<commit-sha>`). This also means never `curl | bash` to install tools like
|
||||
pyenv, nvm, rustup, etc. Instead, download a specific release archive from
|
||||
GitHub, verify its hash (hardcoded in the Dockerfile or script), and only then
|
||||
install. Unverified install scripts are arbitrary remote code execution. This
|
||||
is the single most important rule in this document. Double-check every
|
||||
external reference in every file before committing.
|
||||
|
||||
There is one exception: a package from the distribution's own package index
|
||||
needs no version and no hash. Pulling that index is also allowed. The
|
||||
distribution is trusted. In a `Dockerfile`, it is the pinned base image's
|
||||
distribution. On a host, it is the host's. These commands are examples:
|
||||
- `apt-get update`
|
||||
- `apt-get install`
|
||||
- `apk update`
|
||||
- `apk add`
|
||||
|
||||
These are not trusted, so everything from them stays pinned by hash:
|
||||
- Docker Hub
|
||||
- PyPI
|
||||
- npm
|
||||
- `go get`
|
||||
|
||||
A package source that a `Dockerfile` adds itself is not the distribution's
|
||||
own, so the exception does not cover it.
|
||||
- **ALL external references must be pinned by cryptographic hash.** This
|
||||
includes Docker base images, Go modules, npm packages, GitHub Actions, and
|
||||
anything else fetched from a remote source. Version tags (`@v4`, `@latest`,
|
||||
`:3.21`, etc.) are server-mutable and therefore remote code execution
|
||||
vulnerabilities. The ONLY acceptable way to reference an external dependency
|
||||
is by its content hash (Docker `@sha256:...`, Go module hash in `go.sum`, npm
|
||||
integrity hash in lockfile, GitHub Actions `@<commit-sha>`). No exceptions.
|
||||
This also means never `curl | bash` to install tools like pyenv, nvm, rustup,
|
||||
etc. Instead, download a specific release archive from GitHub, verify its hash
|
||||
(hardcoded in the Dockerfile or script), and only then install. Unverified
|
||||
install scripts are arbitrary remote code execution. This is the single most
|
||||
important rule in this document. Double-check every external reference in
|
||||
every file before committing. There are zero exceptions to this rule.
|
||||
|
||||
- Every repo with software must have a root `Makefile` with these targets:
|
||||
`make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes),
|
||||
@@ -250,8 +233,6 @@ style conventions are in separate documents:
|
||||
# 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
|
||||
@@ -260,24 +241,15 @@ style conventions are in separate documents:
|
||||
ARG CACHEBUST
|
||||
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
|
||||
go test -count=1 -timeout 90s -race -cover ./... || \
|
||||
{ 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 ./
|
||||
@@ -413,10 +385,11 @@ style conventions are in separate documents:
|
||||
`Pipfile.lock`. It installs no Python there: the tests use the base
|
||||
image's Python, which the image's hash pins. If it installs anything else
|
||||
there, the step goes after `ARG CACHEBUST`.
|
||||
- PyPI is not trusted, so `script/bootstrap` installs pipenv and its
|
||||
dependencies by hash. It does so with `pip install --require-hashes -r`
|
||||
and a requirements file in `script/` that lists each of them with `==` and
|
||||
its `--hash`. pip refuses to install a dependency the file does not list.
|
||||
- Every external reference must be pinned by hash, so `script/bootstrap`
|
||||
installs pipenv and its dependencies by hash. It does so with
|
||||
`pip install --require-hashes -r` and a requirements file in `script/`
|
||||
that lists each of them with `==` and its `--hash`. pip refuses to install
|
||||
a dependency the file does not list.
|
||||
- It then runs `pipenv install --deploy`, with `--dev` when the tests need
|
||||
the development packages. `--deploy` installs only what `Pipfile.lock`
|
||||
names, checks every package against the lockfile's hashes, and fails when
|
||||
@@ -440,8 +413,7 @@ style conventions are in separate documents:
|
||||
`pipenv install --dev --deploy`:
|
||||
|
||||
```dockerfile
|
||||
# Test phase. Both pytest runs share one 90-second timeout, so a hang
|
||||
# uses it once and gets no rerun.
|
||||
# Test phase. The 90-second timeout covers both pytest runs.
|
||||
# python:3.x-slim, YYYY-MM-DD
|
||||
FROM python@sha256:... AS test
|
||||
# make and git are base tools that script/bootstrap installs when they
|
||||
@@ -512,19 +484,15 @@ style conventions are in separate documents:
|
||||
improvement bug against that repo. Add a 90-second timeout to the test
|
||||
invocation (`go test -timeout 90s`). The backstop deliberately sits above the
|
||||
hard cap so that it catches a genuinely hung test rather than a merely slow
|
||||
one. A hung package uses the backstop once, because a first run that timed out
|
||||
gets no rerun. `-timeout` applies to each package, so several hung packages
|
||||
can each use it.
|
||||
one.
|
||||
|
||||
- **The test command should use the conditional verbose rerun pattern.** Run
|
||||
tests without `-v` (verbose) first. If tests fail, automatically rerun with
|
||||
`-v` to show full output. This keeps CI logs and `docker build` output clean
|
||||
on success (just package/suite summaries) while providing full diagnostic
|
||||
detail on failure (every test case, every assertion). A first run that timed
|
||||
out gets no rerun, because the rerun would only wait for the same hang. The
|
||||
command lives in the `test` phase of the `Dockerfile`, since `script/test`
|
||||
builds that phase; the Makefile form below is the same pattern for any
|
||||
repo-local invocation:
|
||||
detail on failure (every test case, every assertion). The command lives in the
|
||||
`test` phase of the `Dockerfile`, since `script/test` builds that phase; the
|
||||
Makefile form below is the same pattern for any repo-local invocation:
|
||||
|
||||
```makefile
|
||||
test:
|
||||
@@ -537,29 +505,11 @@ style conventions are in separate documents:
|
||||
|
||||
```makefile
|
||||
test:
|
||||
@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
|
||||
@go test -count=1 -timeout 90s -race -cover ./... || \
|
||||
{ echo "--- Rerunning with -v for details ---"; \
|
||||
go test -count=1 -timeout 90s -race -v ./...; exit 1; }
|
||||
```
|
||||
|
||||
The first run's output is kept so that the recipe can look in it for what Go
|
||||
prints for a hang:
|
||||
- `panic: test timed out` means the test's own timer fired.
|
||||
- `*** Test killed` means `go test` stopped a test that ignored that timer,
|
||||
about a minute later.
|
||||
|
||||
Go prints the goroutine stacks with either line, as long as the test can
|
||||
still respond. A rerun would only wait for the same hang, so the recipe
|
||||
exits 1. A failure with neither line in its output reruns with `-v`. The
|
||||
kept output prints when the first run ends, not while it runs.
|
||||
|
||||
`-count=1` is required on both invocations: it defeats Go's test _result_
|
||||
cache, so neither run can report a stored pass in place of running the
|
||||
tests. It leaves the build cache alone, so it costs the runtime of the suite
|
||||
@@ -578,25 +528,17 @@ style conventions are in separate documents:
|
||||
|
||||
```makefile
|
||||
test:
|
||||
@timeout 90 sh -c 'python -m pytest || { \
|
||||
echo "--- Rerunning with -v for details ---"; \
|
||||
python -m pytest -v; exit 1; }'
|
||||
@python -m pytest || \
|
||||
{ echo "--- Rerunning with -v for details ---"; \
|
||||
python -m pytest -v; exit 1; }
|
||||
```
|
||||
|
||||
Both pytest runs share that one 90-second timeout, as in the `Dockerfile`
|
||||
example above, so a hang uses it once and gets no rerun. Ctrl-C does not
|
||||
stop a running `make test`, which goes on until the tests end or the 90
|
||||
seconds run out. On a Mac without `timeout`, the target fails until it is
|
||||
installed.
|
||||
|
||||
The `exit 1` ensures the target always fails after a rerun — the first run
|
||||
already proved the tests are broken, so the build must not pass even if a
|
||||
flaky test happens to succeed on the second attempt. The rerun exists solely
|
||||
for diagnostic output.
|
||||
|
||||
- Docker builds must complete in under 5 minutes. A hung package uses the
|
||||
90-second test backstop once, because a first run that timed out gets no
|
||||
rerun.
|
||||
- Docker builds must complete in under 5 minutes.
|
||||
|
||||
- `make check` must not modify any files in the repo. Tests may use temporary
|
||||
directories.
|
||||
|
||||
Reference in New Issue
Block a user