REPO_POLICIES.md now carries the canonical script/bootstrap snippet for Go
repos alongside the .golangci.yml bullet, where the pinned linter version
already lives.
The guard it replaces, `if missing golangci-lint; then go install ...; fi`,
tests PATH presence and never version, so on any already-provisioned machine
the pin is inert and a version bump is a no-op. The Dockerfile installs
unconditionally into a clean image, so CI and local then disagree about what
the linter is: a local `make check` green while `make docker` rejects the same
commit, and a container run surfacing findings the host run cannot see.
Comparing versions alone is not enough. `go install` writes to GOBIN (or
GOPATH/bin) while callers resolve through PATH, so a shadowing binary earlier
in PATH lets the install succeed and change nothing a caller ever sees, while
bootstrap prints success. The canonical form therefore compares the installed
version against the pin, re-resolves through PATH after installing and asserts
the pin, and treats any unparseable --version output as a mismatch so the
failure direction is a redundant install rather than a skipped one.
The comparison is exact over the whole version token. A parser that stops at
the first `-` reports 2.12.2 for a host running 2.12.2-rc1, which compares
equal to a 2.12.2 pin and skips the install -- the original defect, reachable
through the comparison meant to close it, and not caught by requiring the pin
to be tagged, since a pre-release is tagged too.
When the assert fails the diagnosis is derived from the resolved path rather
than asserted: a path outside the install directory is shadowing and the
operator is told to remove it or reorder PATH; a path inside it is not, and
saying so would send them after a fault that does not exist; no resolution at
all means the install directory is simply absent from PATH. A trailing slash
on GOBIN is normalised away, since it would otherwise make the inside-the-
directory test miss and misreport shadowing.
The snippet ends with a call site, and both success paths print a confirmation
naming the version. Two definitions with no invocation are a silent no-op with
exactly the shape this change exists to close, and a success path that prints
nothing is byte-identical to that no-op: same exit status, same empty output.
The version helper ends in `|| true` so a --version that exits non-zero cannot
kill the script through `set -e` under `set -o pipefail` before the diagnostic
is printed, which the styleguide's bash form would otherwise do.
The policy text states each of those as a requirement rather than leaving them
implicit in the code, and records why the commit-pinned `go install` ref
satisfies the hash-pinning rule: a commit hash is not a mutable tag, and the
checksum database verifies the fetch, with no repo go.sum consulted, since
`go install pkg@version` ignores the go.mod in the current directory or any
parent. Whether a go.mod tool dependency should replace that is an open
decision and is linked rather than settled here. The two version strings must
be kept in sync and must match exactly what --version prints; tagged pins are
preferred because the expected string is then derivable from the ref, rather
than because the comparison cannot handle a pseudo-version.
Verification runs the controls against the block as a consuming repo would
adopt it, pasted into a script/bootstrap-shaped file and executed, rather than
sourcing it and calling the function directly.
The node and yarn handling described earlier in the document is untouched.
Model: opus-5
Split quickstart into separate repo-policy and code-style passes, clone
prompts repo once instead of per-command, and make each prompt
self-contained so agents don't need memory of prior runs.
- Add test requirement item to both checklists (must not be a no-op)
- Add .dockerignore template URL to Dockerfile items in both checklists
- Add REPO_POLICIES.md symlink in repo root pointing to prompts/
- Add comment to Makefile explaining why prettier flags are repeated
- Move title and last_modified to YAML front matter (all policy docs)
- Make all document sections H1, subsections H2
- Update version rule to reference front matter format
- Fix "our" → "your" typo in Go styleguide
- Fix Python styleguide numbering (2. → 1.)
- Fix README: "flat collection" → accurate description, remove stale TODO
- Remove Makefile items from code styleguides (repo stuff, not code),
add note linking to Repository Policies
- Change zerolog → slog in Go styleguide
- Fix JS styleguide npm reference: both work, but use make targets
- Drop .json from healthcheck path, add JSON content-type requirement
- Add Author/License to Go HTTP Server Conventions
- Convert hyperlinks to backtick URLs in checklists for consistency
- Add version/front matter to both checklists
- Add .golangci.yml from upaas as authoritative copy in this repo
- Update REPO_POLICIES.md to reference .golangci.yml by URL
- Add fetch URLs for all template files in both checklists:
.gitignore, .editorconfig, Makefile, .prettierrc, .prettierignore,
REPO_POLICIES.md, .golangci.yml, check.yml
- Rename REPO_POLICIES.md heading from "Development Policies" to
"Repository Policies" to distinguish from code styleguides
- Move version line above heading per convention
- Add scope statement and links to code styleguide documents
- Add missing Makefile and LICENSE to minimum files list
- Add version lines to all cross-project docs (CODE_STYLEGUIDE*.md,
GO_HTTP_SERVER_CONVENTIONS.md)
- Clean up CODE_STYLEGUIDE.md heading (was old repo name)
- Update EXISTING_REPO_CHECKLIST.md link text to match new heading
- All Dockerfiles must run make check as a build step
- Every repo needs a Gitea Actions workflow running docker build on push
- Greatly strengthen the hash-pinning rule: explicitly list all reference
types, ban curl|bash installs, mark as most important rule in document
- Add model .gitea/workflows/check.yml pinned by commit hash
- Never commit secrets; comprehensive .gitignore with fetch URL
- Never force-push to main
- go mod tidy before committing
- make hooks target with Go repo detection
- Add .editorconfig, .prettierrc, .prettierignore
- Template files URL for new repo setup
- Prettier config required for documentation/writing repos
- Migrations must live in internal/db/migrations/ and be embedded
- Avoid cluttering repo root; canonical subdirectory names listed
- Never use git add -A; always stage files by name
- Makefile must provide make hooks target for pre-commit setup
- All repos should have .editorconfig
- JS required files: yarn.lock, .prettierrc, .prettierignore
- Python required files: pyproject.toml
Add .gitignore, LICENSE (MIT), Makefile, Dockerfile, .dockerignore,
and pin prettier via yarn lockfile for integrity-checked markdown
formatting. Update REPO_POLICIES.md self-reference to point to this
repo. Format markdown files with prettier.
sneak