1 Commits

Author SHA1 Message Date
d0668adc09 policy: name script/check as the gate repo-type verifications belong in
All checks were successful
check / check (push) Successful in 16s
The rule put repo-type-specific extras such as `go mod tidy`
verification in `script/precommit`. `script/precommit` is one caller of
`script/check`, not the gate: a check placed there alone runs only for
contributors who installed the hook, and never in CI. Naming
`script/check` instead puts the check on every path that already funnels
through it, including the Dockerfile build step and therefore CI, with
the pre-commit hook inheriting it.

Records the read-only constraint that placement implies, since
`make check` must not modify files.
2026-08-20 03:06:31 +00:00
3 changed files with 21 additions and 53 deletions

View File

@@ -13,6 +13,7 @@ linters:
disable:
# Genuinely incompatible with project patterns
- exhaustruct # Requires all struct fields
- depguard # Dependency allow/block lists
- godot # Requires comments to end with periods
- wsl # Deprecated, replaced by wsl_v5
- wrapcheck # Too verbose for internal packages
@@ -27,32 +28,6 @@ linters:
max-complexity: 15
dupl:
threshold: 100
depguard:
# Test-support code must not be compiled into the shipped binary. A
# 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.
#
# 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
# import path against a list of prefixes, so it cannot be told "any path
# whose last segment ends in test"; a repository's own test-support
# packages have to be named here one at a time, by full import path,
# under a module path that differs from repository to repository. Add
# them; change nothing else.
rules:
test-support:
list-mode: lax
files:
- "$all"
- "!$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.
issues:
max-issues-per-linter: 0

View File

@@ -124,15 +124,10 @@ last_modified: 2026-03-18
1. Keep the `main()` function as small as possible.
1. Keep the `main` package as small as possible. Each `cmd/<name>/` directory
contains a single `main.go` whose body is one call into library code (for
example `os.Exit(cli.Main())` calling `internal/cli`). All CLI logic — flag
parsing, subcommand dispatch, argument handling, output formatting — lives
in `internal/` or `pkg/`, not in `cmd/`. `main` is just an entrypoint to
your code, not a place for implementations. Exception: single-file scripts.
1. No project logic outside `internal/` or `pkg/`. Anything in `cmd/` is a thin
entrypoint only.
1. Keep the `main` package as small as possible. Move as much code as is
feasible to a library package, even if it's an internal one. `main` is just
an entrypoint to your code, not a place for implementations. Exception:
single-file scripts.
1. HTTP HandleFuncs should be returned from methods or functions that need to
handle HTTP requests. Don't use methods or your top level functions as

View File

@@ -1,6 +1,6 @@
---
title: Repository Policies
last_modified: 2026-08-19
last_modified: 2026-08-20
---
This document covers repository structure, tooling, and workflow standards. Code
@@ -69,8 +69,15 @@ style conventions are in separate documents:
outputs the project's name. Scripts that need the name call
`script/projectname` — e.g. `script/docker` assembles its image tag from it —
so those scripts stay byte-identical across all repos. Repo-type-specific
pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
`script/precommit`, not in the hook itself. Model scripts are at
verifications (e.g. `go mod tidy` verification in Go repos) belong in
`script/check`, which is the gate the other entrypoints funnel through: it
runs in the Dockerfile build step and therefore in CI, and `script/precommit`
inherits it by calling `script/check`. In `script/precommit` alone such a
check binds only the contributors who installed the hook, and the hook file
itself stays a shim that carries no checks of its own. Anything added to
`script/check` must be read-only, since `make check` must not modify files, so
use a verify or diff mode (`go mod tidy -diff`) rather than a command that
rewrites the tree. Model scripts are at
`https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
must document the provided scripts in an **Entrypoints** section (see the
README requirements below).
@@ -263,18 +270,11 @@ style conventions are in separate documents:
- Make all changes on a feature branch. You can do whatever you want on a
feature branch.
- `.golangci.yml` is standardized. The vendored copy in a consuming repo must
_NEVER_ be modified by an agent: fetch it from
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and keep it
byte-identical, so that no repo can quietly loosen its own linting. Linter
configuration changes are made to the canonical copy in the `prompts` repo and
reach consuming repos by re-vendoring; an agent may open a PR against
canonical, which only the user merges. One list is exempt from byte-identity,
because it cannot be written once for every repo: the `deny` list of the
`test-support` depguard rule, where a repo names its own test-support packages
by full import path. A repo adds entries there and changes nothing else, and a
re-vendor carries its entries forward. The canonical golangci-lint version is
v2.12.2 (released 2026-05-06), installed commit-pinned via
- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
manually by the user. Fetch from
`https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`. The
canonical golangci-lint version is v2.12.2 (released 2026-05-06), installed
commit-pinned via
`go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5`.
- When pinning images or packages by hash, add a comment above the reference
@@ -394,9 +394,7 @@ style conventions are in separate documents:
language-specific config). Everything else goes in a subdirectory. Canonical
subdirectory names:
- `bin/` — executable scripts and tools
- `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
body is a single call into `internal/` or `pkg/`, no project logic in
`cmd/`
- `cmd/` — Go command entrypoints
- `configs/` — configuration templates and examples
- `deploy/` — deployment manifests (k8s, compose, terraform)
- `docs/` — documentation and markdown (README.md stays in root)