From 93de4f1758d7f04682995fc4380e3d63df61f4be Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Mon, 16 Nov 2026 23:36:08 +0000 Subject: [PATCH] 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 --- prompts/REPO_POLICIES.md | 95 +++++++++++++++------------------------- 1 file changed, 36 insertions(+), 59 deletions(-) diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index cb2fd11..5002521 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -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/`. 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/`. - 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`, 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` 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