chore(packaging): CHANGELOG.md ships in every npm tarball (#4261) - #4297
Merged
Conversation
AGENTS.md's post-task checklist requires breaking changesets to carry their FROM -> TO migration because "this text ships to consumers as CHANGELOG.md inside the npm package and is what an upgrading agent greps after the tombstone error." That delivery path was severed for 68 of the 69 publishable packages: npm packs package.json / README* / LICENSE* unconditionally but -- unlike older npm versions -- not CHANGELOG.md, and the canonical ["dist", "README.md"] whitelist never named it. Measured on npm 10.9.7: npm pack --dry-run on @objectstack/types shipped 3 files while its 70KB CHANGELOG.md stayed behind. Only @objectstack/spec listed it explicitly. The tombstone scenario is precisely the one where the repo is out of reach -- the upgrading agent has node_modules and nothing else -- so the migration text has to ride in the tarball (#4261's direction 1: make the convention true rather than rewrite it). Every publishable package now declares CHANGELOG.md in `files`, and check:published-files gains a fifth invariant, COMPLETE: a whitelist that fails to cover CHANGELOG.md fails the always-required lint job, so the next package cannot silently sever the path again. CHANGELOG.md joins the canonical set (["dist", "README.md", "CHANGELOG.md"]), which dissolves @objectstack/spec's per-package EXTRA_ENTRIES exemption for it. Verified: --self-test (21 pattern + 11 classification cases, three new pinning the shapes COMPLETE resolves through); the full check green over 69 packages; removing the entry from one package fails the gate with the #4261 story and the one-line fix; npm pack --dry-run on @objectstack/types now lists the 70.8KB CHANGELOG.md. Closes #4261. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 68 package(s): 86 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
59 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #4261.
问题
AGENTS.md的 Post-Task Checklist 要求 breaking changeset 写清 FROM → TO 迁移,理由是这段文字「ships to consumers asCHANGELOG.mdinside the npm package and is what an upgrading agent greps after the tombstone error」。但这条送达路径在 69 个可发布包里断了 68 条:npm 无条件打包的只有package.json/README*/LICENSE*(老版本 npm 曾包含 CHANGELOG,现在不含),而 canonical 白名单["dist", "README.md"]从未列过它。实测(npm 10.9.7)@objectstack/types:tarball 3 个文件,70KB 的CHANGELOG.md留在了仓库里。只有@objectstack/spec显式列了它。撞到 tombstone 报错的场景恰恰是「本地只有
node_modules、没有仓库」的场景 —— 迁移说明必须坐在 tarball 里才 grep 得到。按 issue 的方向 1 落地:让约定成真,而不是改写约定。改了什么
1. 68 个包的
files补上"CHANGELOG.md",canonical 白名单变为["dist", "README.md", "CHANGELOG.md"]。每个包磁盘上都已有 CHANGELOG.md(changesets 维护),无一例外。2.
check:published-files新增第五条不变量 COMPLETE:白名单没有覆盖CHANGELOG.md的包直接挂在始终必跑的lintjob 上,报错正文带 #4261 的因果和一行修法 —— 下一个新包不可能再静默切断这条路径。CHANGELOG.md进入 CANONICAL 集合(声明无需理由),同时进入新的 REQUIRED 集合(不声明就报错)。两者分开:CANONICAL 是「可以」,REQUIRED 是「必须」。@objectstack/spec在EXTRA_ENTRIES里的 CHANGELOG.md 登记随之溶解进 canonical 集合(双向核对会把留下的死条目当错误,所以必须删)。ALWAYS_PACKED的注释同步改写:CHANGELOG 不在 npm 无条件打包集里,正是 COMPLETE 存在的原因。验证
--self-test:21 个模式断言 + 11 个分类断言,新增 3 个钉住 COMPLETE 所依赖的匹配形状(字面量命中、dist不吞它、CHANGELOG.mdx近似名不误命中)。pnpm check:published-files:69 个可发布包全绿。npm pack --dry-runon@objectstack/types:tarball 现在含 70.8kBCHANGELOG.md(issue 里实测缺失的正是它);@objectstack/spec不回归。pnpm lint(改动脚本零告警)、check:nul-bytes/check:doc-authoring/check:role-word/check:org-identifier/check:release-notes、check-changeset-no-major(本 changeset 全 patch)、check-changeset-fixed均通过。changeset status解析通过。顺带发现,未塞进本 PR
.changeset/adapter-hono-auth-wildcard-yields.md仍引用改名前的@objectstack/adapter-hono(现为@objectstack/hono),changeset status/changeset version会在它上面崩 —— 预存在于 main,与本 PR 无关,已另行处理。🤖 Generated with Claude Code