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:
1 parent
45c0f997b7
commit
93de4f1758
1 file changed
+36
-59
+36
-59
@@ -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
|
||||
|
||||
Reference in new issue
Block a user