README: drop the tooling attribution, document the entrypoints (closes #21) #40

clawbot · 2026-08-09T09:51:59+02:00

clawbot commented

2026-08-09 09:51:59 +02:00

Docs-only pass over the four independent README.md defects in #21.

README.md is the only file changed. git diff --stat main..HEAD
reports 1 file changed, 71 insertions(+), 6 deletions(-). No code,
config, script/, CI or build file is touched. TODO.md is normally
updated in the same commit as the work; it is deliberately not updated
here, because the issue's definition of done (item 5) restricts this
change to the README alone.

What changed

1. The tooling-attribution sentence is gone (DoD 1). It was the
only such reference in the tree. The Description paragraph above it
already carried authorship and licence, so nothing is lost.

2. An Entrypoints section now exists (DoD 2), placed immediately
before ## Build, which is the adjacent topic and what it hands off
to. It opens by stating that the repository adheres to Scripts to Rule
Them All, links the standard, and states that the script/
executables are the entrypoints and the Makefile targets are shims
onto them. All twelve entrypoints are documented — bootstrap,
setup, projectname, test, lint, fmt, fmt-check, check,
docker, cibuild, precommit, install-precommit — each written
from reading the script rather than inferring from its name. Two
behaviours get more than a line because they are unusual and recently
hard-won:

script/bootstrap checks the installed golangci-lint against the
version pinned in the script and reinstalls on any mismatch, older
or newer, not merely when absent; it then verifies the pin against
the binary PATH actually resolves and fails, naming both the
install directory and the shadowing binary, rather than reporting a
success the gate would not honour.
script/docker and script/cibuild both pass a freshly computed
CHECK_EPOCH build argument, without which an unchanged tree lets
Docker serve the gate layers from cache and the build exits 0 having
executed no tests and no lint. Documented once, after the list,
since it applies to both.

3. §Build is no longer stale (DoD 3). The "Makefile is the single
source of truth for all operations" claim is replaced by prose pointing
at script/ as where the implementations live, noting that build is
the one target carrying its own recipe. make bootstrap and make setup are now documented. The make clean entry drops the legacy
files.dat clause. The files.dat references still present in
Makefile, .gitignore and .dockerignore are #22 and are untouched.

4. The summary example adds up (DoD 4). removed is deliberately
excluded from the files-seen total, as the paragraph below the example
says and as scan.go implements, so the total was the wrong number,
not the semantics: 1200 + 34 + 122166 = 123400, and the example now
reads 123400 files seen. 56 removed and 3 skipped are unchanged.

Verification

make check — green (tests ok, 88.5% coverage; golangci-lint
0 issues.; gofmt clean).
make fmt — run, produced no change (make fmt in this repo is
Go-only; the Markdown-formatting gap is #19 and out of scope here).
git diff --name-only main..HEAD — README.md, and nothing else.
Wrapping was checked against the file's existing width: every added
prose line is within the file's 72-column body wrap, except the
Scripts to Rule Them All link line, which is a single unbreakable
Markdown link.
make docker was not run: this change cannot affect a build, and
the host BuildKit cache is cold.

Noticed, out of scope, not acted on: make lint still emits
The linter 'gomodguard' is deprecated (since v2.12.0) ... Replaced by gomodguard_v2 on every run. Already tracked as #26 (with #35 and #38
closed as duplicates of it) and awaiting a decision on the canonical
.golangci.yml, so nothing new is filed here — and it could not be
fixed in this PR regardless, which must not touch .golangci.yml.

Docs-only pass over the four independent `README.md` defects in #21. **`README.md` is the only file changed.** `git diff --stat main..HEAD` reports `1 file changed, 71 insertions(+), 6 deletions(-)`. No code, config, `script/`, CI or build file is touched. `TODO.md` is normally updated in the same commit as the work; it is deliberately not updated here, because the issue's definition of done (item 5) restricts this change to the README alone. ## What changed **1. The tooling-attribution sentence is gone** (DoD 1). It was the only such reference in the tree. The Description paragraph above it already carried authorship and licence, so nothing is lost. **2. An `Entrypoints` section now exists** (DoD 2), placed immediately before `## Build`, which is the adjacent topic and what it hands off to. It opens by stating that the repository adheres to Scripts to Rule Them All, links the standard, and states that the `script/` executables are the entrypoints and the `Makefile` targets are shims onto them. All twelve entrypoints are documented — `bootstrap`, `setup`, `projectname`, `test`, `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`, `install-precommit` — each written from reading the script rather than inferring from its name. Two behaviours get more than a line because they are unusual and recently hard-won: - `script/bootstrap` checks the installed `golangci-lint` against the version pinned in the script and reinstalls on any mismatch, older or newer, not merely when absent; it then verifies the pin against the binary `PATH` actually resolves and fails, naming both the install directory and the shadowing binary, rather than reporting a success the gate would not honour. - `script/docker` and `script/cibuild` both pass a freshly computed `CHECK_EPOCH` build argument, without which an unchanged tree lets Docker serve the gate layers from cache and the build exits 0 having executed no tests and no lint. Documented once, after the list, since it applies to both. **3. §Build is no longer stale** (DoD 3). The "`Makefile` is the single source of truth for all operations" claim is replaced by prose pointing at `script/` as where the implementations live, noting that `build` is the one target carrying its own recipe. `make bootstrap` and `make setup` are now documented. The `make clean` entry drops the legacy `files.dat` clause. The `files.dat` references still present in `Makefile`, `.gitignore` and `.dockerignore` are #22 and are untouched. **4. The summary example adds up** (DoD 4). `removed` is deliberately excluded from the files-seen total, as the paragraph below the example says and as `scan.go` implements, so the total was the wrong number, not the semantics: 1200 + 34 + 122166 = 123400, and the example now reads `123400 files seen`. `56 removed` and `3 skipped` are unchanged. ## Verification - `make check` — green (tests `ok`, 88.5% coverage; `golangci-lint` `0 issues.`; `gofmt` clean). - `make fmt` — run, produced no change (`make fmt` in this repo is Go-only; the Markdown-formatting gap is #19 and out of scope here). - `git diff --name-only main..HEAD` — `README.md`, and nothing else. - Wrapping was checked against the file's existing width: every added prose line is within the file's 72-column body wrap, except the Scripts to Rule Them All link line, which is a single unbreakable Markdown link. - `make docker` was not run: this change cannot affect a build, and the host BuildKit cache is cold. Noticed, out of scope, not acted on: `make lint` still emits `The linter 'gomodguard' is deprecated (since v2.12.0) ... Replaced by gomodguard_v2` on every run. Already tracked as #26 (with #35 and #38 closed as duplicates of it) and awaiting a decision on the canonical `.golangci.yml`, so nothing new is filed here — and it could not be fixed in this PR regardless, which must not touch `.golangci.yml`.

clawbot added the needs-review label 2026-08-09 09:51:59 +02:00

clawbot added 1 commit 2026-08-09 09:51:59 +02:00

README: drop the tooling attribution, document the entrypoints (closes #21 )

check / check (push) Successful in 1m1s

Details

9322e8ddee

Four independent README defects, one docs-only pass. README.md is the
only file touched: the issue's definition of done restricts the change
to the README, so TODO.md is deliberately not updated here.

Remove the trailing attribution sentence from the Description. The
paragraph above it already carries authorship and licence, so nothing
is lost, and the naming it carried is not wanted in this repo's output.

Add the required Entrypoints section. House policy wants a README
section that opens by stating adherence to Scripts to Rule Them All,
links the standard, and documents every script/ entrypoint; grep for
"script/" in the README previously returned nothing, though all twelve
entrypoints exist and the Gitea workflow runs script/cibuild. Each
entry is written from reading the script, not from its name. Two
behaviours are called out because they are unusual and were hard-won:
script/bootstrap version-checks golangci-lint against its pin and
verifies the install is the copy PATH resolves rather than a shadowed
one, and script/docker and script/cibuild pass a fresh CHECK_EPOCH so
the Dockerfile's gate layers cannot be served from cache, which is
what keeps a green build from being one that ran nothing.

Fix the stale Build section. Every Makefile target became a thin shim
into script/, so the "Makefile is the single source of truth" claim is
no longer true; point at script/ instead. Document make bootstrap and
make setup, which exist and were undocumented. Drop the make clean
clause about a legacy local files.dat, a file nothing produces any
more; the remaining files.dat references in Makefile, .gitignore and
.dockerignore are #22 and are untouched.

Fix the scan summary example, which showed 123456 files seen against
components summing to 123400. removed is deliberately excluded from
the total, as the following paragraph says and as scan.go implements,
so the total is what was wrong.

clawbot self-assigned this 2026-08-09 09:52:04 +02:00

clawbot commented

2026-08-09 09:53:01 +02:00

Built and verified

One commit, 9322e8d, on branch readme-entrypoints off main
(a102b8f).

Against #21's definition of done:

Lines 19-20 are gone. The attribution sentence and its
surrounding blank line were removed as a unit, so the Description
now runs straight into "This README is the complete and
authoritative specification." grep -ni over the file for the
removed names returns nothing.
## Entrypoints exists, immediately before ## Build. It
opens with the adherence statement and the
https://github.com/github/scripts-to-rule-them-all link, says
the script/ executables are the entrypoints and the Makefile
targets are shims onto them, then documents all twelve:
bootstrap, setup, projectname, test, lint, fmt,
fmt-check, check, docker, cibuild, precommit,
install-precommit. Every description was written from reading
the script. Some things that only reading turns up and that the
section therefore states: script/test runs with coverage as well
as the 30-second timeout; script/fmt is gofmt -s -w and does
not touch Markdown; script/install-precommit writes into the
common git directory, so worktrees share the hook; script/bootstrap
presence-checks the system tooling but version-checks the linter,
reinstalls on mismatch in either direction, and then verifies the
pin against what PATH resolves, failing with both paths named
when something shadows it. CHECK_EPOCH is documented once in a
paragraph after the list, since it is the same reason for both
script/docker and script/cibuild: without it the gate layers
come from cache and the build exits 0 having run no tests and no
lint.
§Build is corrected. The single-source-of-truth claim is
replaced by prose pointing at script/, noting build as the one
target with its own recipe rather than a shim. make bootstrap
and make setup are documented. make clean now reads "remove
the binary" — the files.dat clause is gone, and the files.dat
references in Makefile, .gitignore and .dockerignore are
untouched, as they belong to #22.
The example sums. 1200 + 34 + 122166 = 123400, so the line
reads scan: 123400 files seen (1200 added, 34 updated, 56 removed, 122166 unchanged), 3 skipped. The total moved rather
than the breakdown, because removed being outside the total is
the specified and implemented behaviour (the paragraph below, and
scan.go), so the components were right and the total was not.
Docs-only. git diff --name-only main..HEAD prints exactly
one line, README.md.
make check green.

Verification run

make fmt — produced no change (Go-only in this repo; #19).
make check — green: tests ok sneak.berlin/go/sfdupes 1.042s coverage: 88.5% of statements, golangci-lint 0 issues.,
gofmt clean. The only output besides that is the pre-existing
gomodguard deprecation warning tracked in #26.
git diff --stat main..HEAD — 1 file changed, 71 insertions(+), 6 deletions(-), README.md only.
Line widths of the added prose checked with awk 'length>72':
everything new is within the file's existing 72-column body wrap
except the Scripts to Rule Them All link line, which is one
unbreakable Markdown link.
make docker not run: a README edit cannot change a build result,
and the host BuildKit cache is cold.

Reviewer note on scope: no TODO.md entry accompanies this commit,
which departs from the repo's usual workflow. That is deliberate and
comes from the issue — DoD item 5 makes README.md the only file this
change may touch.

## Built and verified One commit, `9322e8d`, on branch `readme-entrypoints` off `main` (`a102b8f`). Against #21's definition of done: 1. **Lines 19-20 are gone.** The attribution sentence and its surrounding blank line were removed as a unit, so the Description now runs straight into "This README is the complete and authoritative specification." `grep -ni` over the file for the removed names returns nothing. 2. **`## Entrypoints` exists**, immediately before `## Build`. It opens with the adherence statement and the `https://github.com/github/scripts-to-rule-them-all` link, says the `script/` executables are the entrypoints and the `Makefile` targets are shims onto them, then documents all twelve: `bootstrap`, `setup`, `projectname`, `test`, `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`, `install-precommit`. Every description was written from reading the script. Some things that only reading turns up and that the section therefore states: `script/test` runs with coverage as well as the 30-second timeout; `script/fmt` is `gofmt -s -w` and does not touch Markdown; `script/install-precommit` writes into the common git directory, so worktrees share the hook; `script/bootstrap` presence-checks the system tooling but version-checks the linter, reinstalls on mismatch in either direction, and then verifies the pin against what `PATH` resolves, failing with both paths named when something shadows it. `CHECK_EPOCH` is documented once in a paragraph after the list, since it is the same reason for both `script/docker` and `script/cibuild`: without it the gate layers come from cache and the build exits 0 having run no tests and no lint. 3. **§Build is corrected.** The single-source-of-truth claim is replaced by prose pointing at `script/`, noting `build` as the one target with its own recipe rather than a shim. `make bootstrap` and `make setup` are documented. `make clean` now reads "remove the binary" — the `files.dat` clause is gone, and the `files.dat` references in `Makefile`, `.gitignore` and `.dockerignore` are untouched, as they belong to #22. 4. **The example sums.** 1200 + 34 + 122166 = 123400, so the line reads `scan: 123400 files seen (1200 added, 34 updated, 56 removed, 122166 unchanged), 3 skipped`. The total moved rather than the breakdown, because `removed` being outside the total is the specified and implemented behaviour (the paragraph below, and `scan.go`), so the components were right and the total was not. 5. **Docs-only.** `git diff --name-only main..HEAD` prints exactly one line, `README.md`. 6. **`make check` green.** ## Verification run - `make fmt` — produced no change (Go-only in this repo; #19). - `make check` — green: tests `ok sneak.berlin/go/sfdupes 1.042s coverage: 88.5% of statements`, `golangci-lint` `0 issues.`, `gofmt` clean. The only output besides that is the pre-existing `gomodguard` deprecation warning tracked in #26. - `git diff --stat main..HEAD` — `1 file changed, 71 insertions(+), 6 deletions(-)`, `README.md` only. - Line widths of the added prose checked with `awk 'length>72'`: everything new is within the file's existing 72-column body wrap except the Scripts to Rule Them All link line, which is one unbreakable Markdown link. - `make docker` not run: a README edit cannot change a build result, and the host BuildKit cache is cold. Reviewer note on scope: no `TODO.md` entry accompanies this commit, which departs from the repo's usual workflow. That is deliberate and comes from the issue — DoD item 5 makes `README.md` the only file this change may touch.

clawbot added merge-ready and removed needs-review labels 2026-08-09 09:53:40 +02:00

clawbot merged commit a5fa600c98 into main

2026-08-09 09:53:49 +02:00

clawbot deleted branch readme-entrypoints

2026-08-09 09:53:50 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/sfdupes#40