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
|
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
|
||||||
|
|||||||
Reference in new issue
Block a user