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`.
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
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-lint0 issues., gofmt clean. The only output besides that is the pre-existing gomodguard deprecation warning tracked in #26.
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.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Docs-only pass over the four independent
README.mddefects in #21.README.mdis the only file changed.git diff --stat main..HEADreports
1 file changed, 71 insertions(+), 6 deletions(-). No code,config,
script/, CI or build file is touched.TODO.mdis normallyupdated 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
Entrypointssection now exists (DoD 2), placed immediatelybefore
## Build, which is the adjacent topic and what it hands offto. 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
Makefiletargets are shimsonto them. All twelve entrypoints are documented —
bootstrap,setup,projectname,test,lint,fmt,fmt-check,check,docker,cibuild,precommit,install-precommit— each writtenfrom 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/bootstrapchecks the installedgolangci-lintagainst theversion pinned in the script and reinstalls on any mismatch, older
or newer, not merely when absent; it then verifies the pin against
the binary
PATHactually resolves and fails, naming both theinstall directory and the shadowing binary, rather than reporting a
success the gate would not honour.
script/dockerandscript/cibuildboth pass a freshly computedCHECK_EPOCHbuild argument, without which an unchanged tree letsDocker 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 "
Makefileis the singlesource of truth for all operations" claim is replaced by prose pointing
at
script/as where the implementations live, noting thatbuildisthe one target carrying its own recipe.
make bootstrapandmake setupare now documented. Themake cleanentry drops the legacyfiles.datclause. Thefiles.datreferences still present inMakefile,.gitignoreand.dockerignoreare #22 and are untouched.4. The summary example adds up (DoD 4).
removedis deliberatelyexcluded from the files-seen total, as the paragraph below the example
says and as
scan.goimplements, so the total was the wrong number,not the semantics: 1200 + 34 + 122166 = 123400, and the example now
reads
123400 files seen.56 removedand3 skippedare unchanged.Verification
make check— green (testsok, 88.5% coverage;golangci-lint0 issues.;gofmtclean).make fmt— run, produced no change (make fmtin this repo isGo-only; the Markdown-formatting gap is #19 and out of scope here).
git diff --name-only main..HEAD—README.md, and nothing else.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 dockerwas not run: this change cannot affect a build, andthe host BuildKit cache is cold.
Noticed, out of scope, not acted on:
make lintstill emitsThe linter 'gomodguard' is deprecated (since v2.12.0) ... Replaced by gomodguard_v2on every run. Already tracked as #26 (with #35 and #38closed as duplicates of it) and awaiting a decision on the canonical
.golangci.yml, so nothing new is filed here — and it could not befixed in this PR regardless, which must not touch
.golangci.yml.Built and verified
One commit,
9322e8d, on branchreadme-entrypointsoffmain(
a102b8f).Against #21's definition of done:
surrounding blank line were removed as a unit, so the Description
now runs straight into "This README is the complete and
authoritative specification."
grep -niover the file for theremoved names returns nothing.
## Entrypointsexists, immediately before## Build. Itopens with the adherence statement and the
https://github.com/github/scripts-to-rule-them-alllink, saysthe
script/executables are the entrypoints and theMakefiletargets 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 readingthe script. Some things that only reading turns up and that the
section therefore states:
script/testruns with coverage as wellas the 30-second timeout;
script/fmtisgofmt -s -wand doesnot touch Markdown;
script/install-precommitwrites into thecommon git directory, so worktrees share the hook;
script/bootstrappresence-checks the system tooling but version-checks the linter,
reinstalls on mismatch in either direction, and then verifies the
pin against what
PATHresolves, failing with both paths namedwhen something shadows it.
CHECK_EPOCHis documented once in aparagraph after the list, since it is the same reason for both
script/dockerandscript/cibuild: without it the gate layerscome from cache and the build exits 0 having run no tests and no
lint.
replaced by prose pointing at
script/, notingbuildas the onetarget with its own recipe rather than a shim.
make bootstrapand
make setupare documented.make cleannow reads "removethe binary" — the
files.datclause is gone, and thefiles.datreferences in
Makefile,.gitignoreand.dockerignoreareuntouched, as they belong to #22.
reads
scan: 123400 files seen (1200 added, 34 updated, 56 removed, 122166 unchanged), 3 skipped. The total moved ratherthan the breakdown, because
removedbeing outside the total isthe specified and implemented behaviour (the paragraph below, and
scan.go), so the components were right and the total was not.git diff --name-only main..HEADprints exactlyone line,
README.md.make checkgreen.Verification run
make fmt— produced no change (Go-only in this repo; #19).make check— green: testsok sneak.berlin/go/sfdupes 1.042s coverage: 88.5% of statements,golangci-lint0 issues.,gofmtclean. The only output besides that is the pre-existinggomodguarddeprecation warning tracked in #26.git diff --stat main..HEAD—1 file changed, 71 insertions(+), 6 deletions(-),README.mdonly.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 dockernot run: a README edit cannot change a build result,and the host BuildKit cache is cold.
Reviewer note on scope: no
TODO.mdentry accompanies this commit,which departs from the repo's usual workflow. That is deliberate and
comes from the issue — DoD item 5 makes
README.mdthe only file thischange may touch.