REPO_POLICIES: Entrypoints

One list now pairs each required target with its script, and one
lists the three scripts with no required target, absorbing the list
of extensions and the pre-commit hook rule; the README sentence goes,
since the README section requires the same; every target, script and
condition stays.

Model: opus-5-5
This commit is contained in:
clawbot committed 2026-11-18 20:25:47 +00:00
1 parent e00c35b53c
commit 876b604f38
1 file changed
+36 -59
+36 -59
View File
@@ -87,72 +87,49 @@ style conventions are in separate documents:
committed, because repos need to work with `go get`, which downloads code
but does not execute code generation.
- Every repo with software must have a root `Makefile` with these targets:
- `make bootstrap`
- `make setup`
- `make test`
- `make lint`
- `make fmt` (writes)
- `make fmt-check` (read-only)
- `make check` (runs `test`, `lint`, `fmt-check`)
- `make docker`
- `make hooks` (installs pre-commit hook)
- `make update-policy` (fetches the vendored policy files, commits and
pushes)
A model Makefile is at
`https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
# Entrypoints
- Repos follow the
[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
pattern. The implementation of each Makefile target lives in an executable
script in `script/`, and the Makefile targets are thin shims that call them:
- `script/bootstrap`
- `script/setup`
- `script/test`
- `script/lint`
- `script/fmt`
- `script/fmt-check`
- `script/check`
- `script/docker`
- `script/update-policy`
pattern. Every repo with software must have a root `Makefile` with the targets
below. Each target is a thin shim that calls an executable script in
`script/`, where its implementation lives:
- `make bootstrap`: `script/bootstrap` installs all dependencies.
- `make setup`: `script/setup` readies a fresh clone for development. It
runs `bootstrap`, then `install-precommit`, plus any repo-specific
initialization.
- `make test`: `script/test`
- `make lint`: `script/lint`
- `make fmt`: `script/fmt` (writes)
- `make fmt-check`: `script/fmt-check` (read-only)
- `make check`: `script/check` runs `script/test`, `script/lint` and
`script/fmt-check`.
- `make docker`: `script/docker`
- `make hooks`: `script/install-precommit` installs the git pre-commit hook.
- `make update-policy`: `script/update-policy` fetches the vendored policy
files from the `prompts` repo, commits them and pushes.
Five further scripts are our own extensions to the standard:
- `script/check` runs `script/test`, `script/lint` and `script/fmt-check`.
- `script/precommit` is what the git pre-commit hook runs, and it calls
`script/check`.
- `script/install-precommit` installs the git pre-commit hook. The
`make hooks` target shims to it.
- `script/update-policy` fetches the vendored policy files from the
`prompts` repo, commits them and pushes. The `make update-policy` target
shims to it.
- `script/projectname` (literally that filename) simply outputs the
project's name.
Scripts that need the name call `script/projectname`, so those scripts stay
byte-identical across all repos. `script/docker`, for example, assembles its
image tag from it. Repo-type-specific pre-commit extras belong in
`script/precommit`, not in the hook itself; `go mod tidy` verification in Go
repos is one. 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).
Three more scripts have no required target:
- `script/precommit` is what the pre-commit hook runs. It calls
`script/check`. Repo-type-specific extras belong in it, not in the hook
itself; `go mod tidy` verification in Go repos is one. If local testing is
not possible in the repo, it may skip `script/test` and run only
`script/lint` and `script/fmt-check`.
- `script/cibuild` runs the CI build, and the Gitea workflow calls it.
- `script/projectname` (literally that filename) outputs the project's name.
Scripts that need the name call it, so they stay byte-identical across all
repos. `script/docker`, for example, assembles its image tag from it.
From the standard's canonical set we use `bootstrap`, `setup`, `test`, and
`cibuild`. `setup` makes the repo ready for development after a fresh clone:
it runs `bootstrap`, then `install-precommit`, plus any repo-specific
initialization.
`cibuild`. `check`, `precommit`, `install-precommit`, `update-policy` and
`projectname` are our own extensions to the standard.
The scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they
run in minimal containers; alpine images, for example, have no bash. Locate
the repo root with `$(cd "$(dirname "$0")/.." && pwd -P)`, and `cd` there
before acting.
- Pre-commit hook: runs `script/precommit`, which calls `script/check`. If local
testing is not possible in the repo, `script/precommit` may skip `script/test`
and run only `script/lint` and `script/fmt-check`. `script/install-precommit`
installs the hook; the Makefile must provide a `make hooks` target that shims
to it.
before acting. A model Makefile is at
`https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`. Model scripts
are at `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`.
- Run the repo's own entrypoints, never the underlying tools directly. The
`script/` scripts are the single source of truth for how each operation runs.
@@ -175,9 +152,9 @@ style conventions are in separate documents:
- seeding data
- anything else a developer would do regularly
If someone checks out the repo and types `make<tab>`, they should see every
meaningful operation available. A new contributor should be able to
understand the entire development workflow by reading the Makefile.
Typing `make<tab>` in a checkout should show every meaningful operation. A
new contributor should be able to understand the entire development workflow
by reading the Makefile.
- A repo updates its policy files with one command: `make update-policy`. It
runs `script/update-policy`, which fetches each vendored file the repo carries