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