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