diff --git a/changelog.d/251.md b/changelog.d/251.md new file mode 100644 index 0000000..7853b80 --- /dev/null +++ b/changelog.d/251.md @@ -0,0 +1,14 @@ +### Added + +- CI now refuses a root `*.md` declared in neither `docs/VENDORED.txt` nor the + guard's short exemption list, so a new doctrine file can no longer reach a + tag undeclared and stay invisible to every consumer's `docs-sync` (#251). +- The same guard reads the manifest the other way: every entry must resolve to + a regular, non-empty, tracked file — no symlink, no directory, no `../` + escape (#251). + +### Changed + +- Consumer guidance: re-vendor tooling reads the pin's `docs/VENDORED.txt`, + never a hardcoded list, so a new doctrine file propagates at the next + ordinary pin bump with zero list edits (#251). diff --git a/docs/CONSUMERS.md b/docs/CONSUMERS.md index 413385f..b684e12 100644 --- a/docs/CONSUMERS.md +++ b/docs/CONSUMERS.md @@ -598,6 +598,37 @@ It is **unreleased** (#248) until that tag exists: consumers add `.ceremony/RELEASES.md` only with the ordinary pin bump and re-sync, never by copying it ahead of their pinned doctrine set. +### Read the manifest, never a copy of it + +Anything on the consumer's side that needs to know *which* documents are +vendored — a re-vendor script, a `docs-sync` equivalent, the task list of a +conversion issue — reads **the pin's `docs/VENDORED.txt`** and never names +the files itself. The manifest is available at the pinned ref from `0.5.0` +and later (ceremony#251); it is one path per line, relative to ceremony's +root, and blank lines are ignored: + +```sh +# the vendored doc set at the ref this repo is pinned to +curl -fsSL "https://raw.githubusercontent.com/heavy-duty/ceremony//docs/VENDORED.txt" +``` + +That is the whole benefit: a doctrine file added in ceremony — `RELEASES.md` +was the last, ceremony#248 — reaches every consumer at its next **ordinary +pin bump**, with **zero list edits** anywhere. A hardcoded list propagates +nothing, and its staleness is silent rather than red: `docs-sync --check` +asserts byte-identity for the files the list names and says nothing at all +about one it omits, so a consumer keeps a green guard while governing +itself with doctrine it no longer has. + +What makes reading the manifest *sufficient* — rather than merely better +than a copy — is that ceremony's CI now refuses a root doctrine file that is +declared in neither the manifest nor a short in-script exemption list +(`.github/scripts/vendored-check.sh`), so the manifest at a tag is the +complete set as of that tag. That guarantee is **unreleased** (#251) until +the first tag carrying it exists; the manifest is worth reading at every +earlier pin regardless, since it is what `actions/docs-sync` has always +mirrored. + The consumer's ci.yml gains the guard alongside the others: ```yaml