diff --git a/.github/scripts/marker-check.sh b/.github/scripts/marker-check.sh index b973f8f..851ed6a 100755 --- a/.github/scripts/marker-check.sh +++ b/.github/scripts/marker-check.sh @@ -7,6 +7,8 @@ # own issue uses bare #N, never a self-qualified repository citation (#238 D8). # CHANGELOG.md is the release oracle and immutable shipped prose, so it and the # fragments that feed it are excluded from the documentation scan (#238 D5). +# A token inside inline code is a mention, not a marker; spans are stripped +# individually so unrelated backticks cannot hide a real marker (#238 D9). # # Usage: marker-check.sh [tree-dir] (default: the repository root) set -euo pipefail diff --git a/docs/CONSUMERS.md b/docs/CONSUMERS.md index cb3f30b..413385f 100644 --- a/docs/CONSUMERS.md +++ b/docs/CONSUMERS.md @@ -117,9 +117,11 @@ the machinery at all: `**unreleased**` immediately followed by its issue citation (for example, `(#238)`); whitespace between them may include a line break. A citation is mandatory, because a marker the guard cannot trace is a marker it cannot - prove false. A marker for this repository's own issue uses bare `#N`. - Cross-repo citations such as `(crew#293)` satisfy the traceability rule but - are not compared with this repository's release section. The ceremony-only + prove false. A token inside an inline-code span is a mention, not a marker; + spans are ignored individually, so unrelated inline code cannot hide one. + A marker for this repository's own issue uses bare `#N`. Cross-repo + citations such as `(crew#293)` satisfy the traceability rule but are not + compared with this repository's release section. The ceremony-only `marker-check.sh` guard enforces these rules. The release PR that ships the machinery clears, in that same PR, every marker its own assembled section makes false: the section cites its issues, each marker cites the same issue, and the release PR's diff is the diff --git a/test/marker-check.test.sh b/test/marker-check.test.sh index ca373fd..0310c8c 100644 --- a/test/marker-check.test.sh +++ b/test/marker-check.test.sh @@ -40,6 +40,26 @@ printf 'The new guard remains **unreleased** for now.\n' \ check "an uncited marker fails on a dev tree with file and line" 1 \ "docs/CONSUMERS.md:1" run_check uncited +fixture inline-mention 0.6.0-dev +cat >"$TMP/inline-mention/docs/CONSUMERS.md" <<'EOF' +The marker token is `**unreleased**`. +EOF +check "an inline-code token is a mention and needs no citation" 0 \ + "agree with the tree" run_check inline-mention + +fixture inline-bare 0.6.0-dev +printf 'The marker token is **unreleased**.\n' \ + >"$TMP/inline-bare/docs/CONSUMERS.md" +check "removing the backticks exposes the uncited marker" 1 \ + "docs/CONSUMERS.md:1" run_check inline-bare + +fixture inline-neighbor 0.6.0-dev +cat >"$TMP/inline-neighbor/docs/CONSUMERS.md" <<'EOF' +The `new guard` remains **unreleased** until its tag. +EOF +check "unrelated inline code cannot hide an uncited marker on the same line" 1 \ + "docs/CONSUMERS.md:1" run_check inline-neighbor + fixture shipped 0.6.0 printf 'The new guard remains **unreleased** (#224).\n' \ >"$TMP/shipped/docs/CONSUMERS.md"