From 883f9ac1535fb6f0c5f22a6b22784ca1b1d378ae Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 30 Jul 2026 10:51:43 +0000 Subject: [PATCH] docs(docs-audit): record why CHANGELOG.md is NOT added to the drift exclusion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #4091 dropped test files before deriving the changed-package roots, because a test cannot make an implementation-accuracy doc stale. `packages/*/CHANGELOG.md` is the obvious next candidate by the same argument — release notes define behaviour no more than a test does — and extending the exclusion there is a provable no-op. Measured before writing anything down: - `chore: version packages` is the only PR class that mass-touches those files, and it runs no GitHub Actions at all. `changesets/action` opens it with the repo's GITHUB_TOKEN, and GitHub does not create workflow runs from GITHUB_TOKEN-authored events. #3910 carries exactly one check run, from Vercel's own app — `ci.yml` matches that PR unconditionally and still never fired. So the drift gate never sees a release PR to be noisy on. - Even if it did, `changeset version` writes `package.json` beside every `CHANGELOG.md` it appends to (45 against 46 on page 1 of #3910's diff), so dropping the CHANGELOGs would leave the derived package-root set identical. The bump is not unverified, just verified later: `ci.yml` and `lint.yml` both run on `push: main`, and `release.yml` gates publish on a green build — worth stating so the absent PR checks are not read as a hole. Recorded in the README beside the exclusion it neighbours, so the next reader does not spend a PR rediscovering it. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01QoA8AV99Ss1RRkLLAYmDzq --- .../docs-audit-changelog-non-exclusion.md | 18 ++++++++++++++++++ scripts/docs-audit/README.md | 18 ++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 .changeset/docs-audit-changelog-non-exclusion.md diff --git a/.changeset/docs-audit-changelog-non-exclusion.md b/.changeset/docs-audit-changelog-non-exclusion.md new file mode 100644 index 0000000000..05cd5f3300 --- /dev/null +++ b/.changeset/docs-audit-changelog-non-exclusion.md @@ -0,0 +1,18 @@ +--- +--- + +Docs only — no package changes, nothing to release. + +Records why `packages/*/CHANGELOG.md` is **not** added to the docs-drift mapper's test-file +exclusion (#4091). It reads as the obvious next narrowing and is a provable no-op: + +- `chore: version packages` is the only PR class that mass-touches those files, and it runs + no GitHub Actions — `changesets/action` opens it with the repo `GITHUB_TOKEN`, which by + design triggers no workflow runs. Measured on #3910: one check run, Vercel's own app. + The version bump is still verified, just post-merge (`ci.yml` / `lint.yml` on `push: main`, + and `release.yml` gates publish on a green build). +- `changeset version` writes `package.json` beside every `CHANGELOG.md` it appends to + (45 vs 46 on page 1 of #3910's diff), so excluding the CHANGELOGs would leave the derived + package-root set bit-identical anyway. + +Written down so the next reader does not spend a PR rediscovering it as a gap. diff --git a/scripts/docs-audit/README.md b/scripts/docs-audit/README.md index d1b4cb8a15..ecb3fdd060 100644 --- a/scripts/docs-audit/README.md +++ b/scripts/docs-audit/README.md @@ -41,6 +41,24 @@ the PR where it is right. The count of excluded files is reported in the summary pins the matcher against paths that must and must not match (`commands/test.ts` is implementation; `foo.conformance.test.ts` is not). +**And one deliberate non-exclusion:** `packages/*/CHANGELOG.md` stays counted, even though +release notes define behaviour no more than a test does. Extending the exclusion there +looks like the obvious next step and is a provable no-op, for two independent reasons: + +1. The only PR class that mass-touches those files is `chore: version packages`, and it + runs **no GitHub Actions at all** — `changesets/action` opens it with the repo's + `GITHUB_TOKEN`, and GitHub does not trigger workflow runs from `GITHUB_TOKEN`-authored + events. Measured on #3910: one check run, from Vercel's own app. So this gate never + sees a release PR to be noisy on. (The bump is still verified — `ci.yml` and `lint.yml` + both run on `push: main`, and `release.yml` gates publish on a green build.) +2. Even if it did run, `changeset version` writes `package.json` next to every + `CHANGELOG.md` it appends to — 45 of the former against 46 of the latter on the first + page of #3910's diff — so dropping the CHANGELOGs would leave the derived package-root + set bit-identical. + +A hand-edited CHANGELOG outside a release is also close to nonexistent in practice. Left +counted, and recorded here so the idea is not rediscovered as a gap. + ## 2. CI gate — `.github/workflows/docs-drift-check.yml` On any PR that touches `packages/**`, runs `affected-docs.mjs` against the base branch