sneak
d351151f45
check / check (push) Failing after 2s
The note under the canonical Go Dockerfile example said to install system libraries for linting with `apk add`, but the lint phase is based on the Debian golangci-lint image, which has no apk. It now gives the apt-get command with the Debian package name (libvips-dev) and removes the package lists in the same RUN. No other canonical sentence describes installing a library in the lint phase; the remaining apk mentions concern the alpine build stage or the host. Nothing is pinned or unpinned. Model: opus-5-5
169 lines
11 KiB
Markdown
169 lines
11 KiB
Markdown
# Workflow
|
|
|
|
- branch (from `main`)
|
|
- do the work in Next Step
|
|
- move Next Step to the top of Completed Steps
|
|
- 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
|
|
- push
|
|
|
|
# Status
|
|
|
|
pre-1.0
|
|
|
|
# Next Step
|
|
|
|
Finish the two draft prompt documents in the working tree and commit them:
|
|
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-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).
|