Author SHA1 Message Date
sneak 4760c67b7a Correct the phase-build comments in script/lint and script/test (closes #141)
check / check (push) Successful in 23s
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.

Model: opus-5-5
2026-11-15 12:59:12 +00:00
5 changed files with 22 additions and 102 deletions

No files matched your search

+16
View File
@@ -177,6 +177,22 @@ subdirectory. Each file contains one or more related prompts or policy
documents. There is no build step or runtime component; the prompts are consumed documents. There is no build step or runtime component; the prompts are consumed
by copying them into other projects or referencing them directly. 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.).
## See Also ## See Also
- **[clawpub](https://git.eeqj.de/sneak/clawpub)** — Real-world examples, - **[clawpub](https://git.eeqj.de/sneak/clawpub)** — Real-world examples,
+2 -98
View File
@@ -1,6 +1,6 @@
--- ---
title: Code Styleguide — Go title: Code Styleguide — Go
last_modified: 2026-11-16 last_modified: 2026-11-07
--- ---
1. Format Go code with `gofmt` and then `golines -m 77`, through `make fmt`. 1. Format Go code with `gofmt` and then `golines -m 77`, through `make fmt`.
@@ -176,7 +176,7 @@ last_modified: 2026-11-16
them a bit long. them a bit long.
1. Use descriptive names for modules and filenames. Avoid generic names like 1. Use descriptive names for modules and filenames. Avoid generic names like
`server`. The rules for package names are under Naming, below. `server`. `util` is banned.
1. Constructors **must** take a `Params` struct (or `ThingParams` when 1. Constructors **must** take a `Params` struct (or `ThingParams` when
`NewThing()` is used), even for a single argument. Named fields in a Params `NewThing()` is used), even for a single argument. Named fields in a Params
@@ -487,102 +487,6 @@ last_modified: 2026-11-16
releasable". "Releasable" in this context means that it builds and functions releasable". "Releasable" in this context means that it builds and functions
as expected, and that all tests and linting passes. 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 name a package `model`, `models`, `util`, `utils`, `common`, `misc`,
`helper`, `helpers`, `types`, `interfaces` or `api`, or anything else that
says nothing about what is in it: every program has a data model, helpers
and types. Name the package for the one thing its code is about; when its
code is about several things, split it first (`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. Never give a package a name that callers want for a variable (`buf`,
`count`) or that a widely used standard package has (`log`, `http`, `url`),
because every importer then has to rename one of the two. Use a longer name
that says which one: `bufio`, `usercount`.
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. Give it a local name only when two
imports have the same name or its own name breaks these rules, and use that
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.
The type a package is named for may carry the same name on its own:
`list.List`, `time.Time`.
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. Only when two
functions differ in nothing but a type does the type go in, at the end:
`ParseInt`, `ParseInt64`.
1. Name a function that returns a value for the value and one that acts for the
action (`JobName(key)`, `WriteDetail(w)`), so that a call reads as what it
gives or what 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. A call that goes to a database or the network takes a verb that says
so (`Fetch`, `Load`), and `Get` stays only where it is the thing's own word,
as in an HTTP GET.
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. Give a method that does what a well-known method does that method's name and
signature: `String()`, never `ToString()`. Give a method that does anything
else another name, because readers and the standard interfaces rely on
`Read`, `Write`, `Close` and `String` 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 the distance between its declaration and its
last use (`i`, `r` and `db` across a few lines, a full word or two across a
long function), because a reader far from the declaration has only the name.
1. Name a receiver with one or two letters, the same in every method of its
type, never `this`, `self` or `me`, because it appears on nearly every line
of those methods.
# Other Golang Tips and Best Practices (Optional) # Other Golang Tips and Best Practices (Optional)
1. For any internet-facing http server, set appropriate timeouts and limits to 1. For any internet-facing http server, set appropriate timeouts and limits to
+2 -2
View File
@@ -8,8 +8,8 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
main() { main() {
cd "$ROOT" cd "$ROOT"
hook=".git/hooks/pre-commit" hook=".git/hooks/pre-commit"
printf '#!/bin/sh\nset -e\nscript/precommit\n' > "$hook" printf '#!/bin/sh\nset -e\nscript/precommit\n' > .git/hooks/pre-commit
chmod +x "$hook" chmod +x .git/hooks/pre-commit
echo "pre-commit hook installed: runs script/precommit" echo "pre-commit hook installed: runs script/precommit"
} }
+1 -1
View File
@@ -1,6 +1,6 @@
#!/bin/sh #!/bin/sh
# script/lint: run the linter. Linting is a phase of the Dockerfile and # script/lint: run the linter. Linting is a phase of the Dockerfile and
# this builds that phase; the linter is never installed or run on # this builds that phase alone; the linter is never installed or run on
# a developer host, where a shared result cache and a host-global lock # a developer host, where a shared result cache and a host-global lock
# make its answer untrustworthy. # make its answer untrustworthy.
# #
+1 -1
View File
@@ -1,6 +1,6 @@
#!/bin/sh #!/bin/sh
# script/test: run the test suite. Testing is a phase of the Dockerfile # script/test: run the test suite. Testing is a phase of the Dockerfile
# and this builds that phase, on the same terms as script/lint: # and this builds that phase alone, on the same terms as script/lint:
# --target so that only the test phase and the stages it depends on are # --target so that only the test phase and the stages it depends on are
# built, and a new CACHEBUST value because a cached test layer is a test # built, 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 # that did not run; unlike --no-cache, it keeps the layers above the ARG