门禁:PR 改动 `packages/*/src/**` 而未新增 `.changeset/*.md` 时失败(空 frontmatter 为显式豁免)

[os-zhuang]

Part of objectstack-ai/objectstack#4904(跨分片转移:落点在本仓,源单留主 backlog 跟踪)

背景

objectstack 侧 #4731 / #4843 已把「哪些前端改动发版」的判据统一为读本仓声明的 .changeset/*.md。该判据的正确性依赖一个本仓前提:改了已发布包源码就必须带 changeset —— 目前没有门禁保证。

实测区间 7d9734d5e321..785b8a5d432c(53 个非 merge 提交)有 7 条无 changeset,其中两条真实改了已发布包源码且为用户可见修复:

提交	改动
19716b5bf fix(charts): name the slices (#3138)	packages/plugin-charts/src/AdvancedChartImpl.tsx、ChartContainerImpl.tsx、packages/plugin-dashboard/src/DatasetWidget.tsx
5e7ef1141 fix(i18n): resolve qualified view ids (#3132)	packages/i18n/src/useObjectLabel.ts

后果:这两条修复不在本仓 CHANGELOG/版本号里,不在平台侧 bump-objectui.sh 写的 console changeset 里,不在发布页 Console 段落里 —— 搭了下一次发版的顺风车,任何发布记录都查不到。

要做什么

加一道 CI 门禁:PR 若改动 packages/*/src/** 且未新增 .changeset/*.md → 失败。

• 空 frontmatter(release-nothing)是合法的显式豁免写法 —— 要的是声明一次,不是强制发版;
• 思路对齐 objectstack 仓的 check:changeset-* 系列:声明即强制,不让消费侧猜;
• 门禁自身按 #4690 反模式防御:输入缺失(diff 取不到、changeset 目录不存在)响亮失败,不静默 exit 0。

关联

• objectstack#4904(源单,含完整分析)
• objectstack#4731 / #4843(判据统一到声明)
• objectstack#3340(共同要防的洞)

[claude]

Cross-link from triage: the root cause of this gap has now been identified, and it changes how this issue should be implemented. objectstack#6174 (filed 2026-08-07) re-discovered this class from a different direction and found something neither this issue nor its source issue (objectstack#4904) records.

This repo already has a changeset-guard.yml, and its trigger is why nothing catches the miss

.github/workflows/changeset-guard.yml exists today. Its trigger:

on:
  pull_request:
    branches: [main, develop]
    paths:
      - '.changeset/**'

So the workflow starts only when .changeset/** changes — and a PR that forgot its changeset, by definition, does not touch .changeset/**. The check that could see the miss is the one check guaranteed not to run on it. Its single job (Changeset Bump Policy) also only enforces the level policy (no major), never "should this change have carried a changeset at all".

Implementation note, and the reason this is worth a comment rather than a silent link: the inverse trigger is deliberate and documented in that file's own header — it exists so that a PR adding only a changeset (which ci.yml and lint.yml both paths-ignore) still gets a check. So the fix here is not to widen that workflow's paths — that would break the case it was built for. This issue needs a separate, forward-triggered gate (fires on packages/*/src/**, asserts a .changeset/*.md was added), living alongside the existing one.

The class is still firing — a fresh instance inside the current pin window

objectui#3518 / commit 0e50440 (fix(form): bind previous for field rules and stop resubmitting read-only fields) — 26 files across packages/components, packages/plugin-form, packages/types, packages/data-objectstack, packages/app-shell and all ten locale packs, plus two new test files. No .changeset/*.md. It shipped inside the 7dfbeb70 release and appears in no CHANGELOG line anywhere; on the platform side it exists only as +1 in a "20 commits carrying no changeset" count.

That is a third instance after the two in this issue's body (19716b5bf, 5e7ef1141), and the first one after objectstack#4843 made the omission audible — evidence that making it audible did not make it stop.

Status of the surrounding work (so this issue's scope stays clean)

• This issue remains the only dispatch entry for the gate itself. objectstack#6174 has been scoped by triage to the platform-side half only (naming the un-declared commits in the console changeset body instead of counting them) and explicitly does not duplicate this work.
• objectstack#4904 stays as the source/tracking issue, Blocked-by: this one.

No label or state change made here — this issue's pm:queue and its ownership by the objectui seat are unchanged.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[yinlianghui]

认领:PM 循环批 181(objectui 整仓席位,登记表 objectstack#4604)

按分诊追评的关键发现执行:现有 changeset-guard.yml 的反向触发(仅 .changeset/** 变更时启动)是刻意设计(服务"只加 changeset 的 PR 也要有检查"),⛔ 不得加宽其 paths——需另建正向触发门禁(改 packages/*/src/** 则断言新增 .changeset/*.md,空 frontmatter 为显式豁免)与之并存。门禁自身循 #4690/objectstack#4928 filter 契约:输入缺失(diff 取不到、目录不存在)响亮失败——与今日刚落地的 PR #3744(docs gate fail-open)同族拼法。共享基础设施复查:ci.yml 今日被 #3722/#3744 改过,新建独立 workflow 文件避开该面;认领时无在飞 PR 触 changeset-guard.yml。

会话:session_01GTRjn8qBqp75dk7kFupVRt → 更正:session_01GTRjn8xBqp75dk7kFupVRt
分支:claude/issue-3387-changeset-presence-gate
Worktree:objectui-3387
文件面:.github/workflows/(新文件)+ scripts/(如需校验脚本/测试)(越界即停)

---

Generated by Claude Code

[yinlianghui]

实现完成,DRAFT PR #3769(分支 claude/issue-3387-changeset-presence-gate,会话 session_01GTRjn8xBqp75dk7kFupVRt)。按分诊追评执行:未动 changeset-guard.yml,另建正向触发门禁 .github/workflows/changeset-presence.yml + scripts/check-changeset-presence.mjs 与之并存。

三点值得在本单上留痕(细节与测量见 PR):

1. 本单提的守护面 packages/*/src/** 漏掉了最关键的一个包。 @object-ui/console 是已发布包(在 .changeset/config.json 的 fixed 组里)、是本仓最常改的包、也正是平台 bump-objectui.sh 替它写 changeset 的那个包 —— 但它住在 apps/console,不在 packages/ 下。若按字面 glob 实现,门禁会漏掉发版判据最主要涉及的那个包。已改为从 .changeset/config.json 的 fixed 组推导守护面(今天 40 个包目录 = 39 个 packages/* + apps/console;ignore 的 @object-ui/site、examples 不守),这样发版覆盖谁门禁就守谁,不会再漂移。

2. 本类问题在已记录的三条之后又发生了两次。 把门禁回放到落地前最近 80 个非 merge 提交:10 条会红,其中 918888a30 fix(fields): echo stored date values in the sub-grid's native date cells 与 dcff16e06 fix(cli,create-plugin) 是用户可见修复且没有 changeset —— 即本单正文的三条(19716b5bf / 5e7ef1141 / 0e50440)之后又各自搭了一次顺风车。另外 5 条只动了 src/ 下的测试文件,一行空 frontmatter 即可。门禁在真实历史上重现了本单记录的全部三条(分别 exit 1,0e50440 报出的 26 个文件与追评记录完全一致)。

3. 三处文档原本会因本门禁变成假话,已一并修正。 content/docs/guide/ci-cd-pipeline.md 原写「Nothing in CI requires a pull request to add a changeset」(该页被 ci-cd-pipeline-doc.test.ts 双向钉住,新增 workflow 本就必须在此建节)、CONTRIBUTING.md 原写「DON'T create a changeset for … apps / 测试改动」、AGENTS.md 原写「纯 bug 修复不需要」—— 而最后这条旧判据正是放走上面几条修复的那一条。

自指冒烟测试(dispatch 第 5 条)已在远端验证:本 PR 自身不碰守护面,Changeset Declaration 在自己的 PR 上跑了并且绿(不是 skipped —— 它没有 path 过滤),14 秒,CI 实测输出:

Compared the working tree with dbc44b4be (merge-base with origin/main): 7 file(s) changed,
0 of them under the src/ of a package the release covers, 0 under a package changesets
ignores, 0 changeset(s) added.
✅  No source of a released package changed in this range, so no changeset is owed.

顺带记录:写测过程中被自己的测试抓出并修掉一个真实缺陷(显式 --base 解析不出时静默跌落到别的提交并报绿,exit 0→1);同族的 check-i18n-en-drift.mjs 仍是该写法,已另开 #3766(本 PR 不动)。另有 #3767(scripts/README.md 整篇在讲两个不存在的脚本,finding)。

合并后 objectstack#4904 即可解除阻塞。PR 保持 draft,不自行合并,等 review。

---

Generated by Claude Code

[yinlianghui]

验收:PR #3769 ACCEPT(会话 session_01GTRjn8xBqp75dk7kFupVRt,PM 循环批 181)。objectstack#4904 随本 PR 落地解锁。

交付内容:正向门禁(changeset-presence.yml + check-changeset-presence.mjs)与反向触发的 changeset-guard 相向而立、互不改动。最重要的订正:守卫面不用字面 glob(会漏掉住在 apps/console 的 @object-ui/console——被编辑最多的已发布包)而从 .changeset/config.json fixed group 派生(40 目录;ignore 表跳过;两表皆无的包响亮失败而非默认未发布)。空 frontmatter 一等公民豁免;无 path filter + 订阅 merge_group 的双偏离有据(context 每 PR 必报 → 可 requirable,#3523 后半);一切输入缺失响亮失败。

证据等级罕见地高:历史重放复现 issue 记录的全部三例(0e50440 的 26 文件与分诊计数逐字吻合)+ 近 80 提交重放再抓两例(918888a、dcff16e06——类在门禁缺席期间持续发作的直接证据);自指冒烟(本 PR 自己的 CI 上门禁真实运行并正确判"不欠");逆向验证三方向,其中一处预测错误如实报告并修正了 fixture 的覆盖指向(原 fixture 钉的是 range 不是 filter;补两枚真达 filter 的,delete 案被双重防御拦住则改钉结局)。扩界三文件全部有据:guide 页是双向钉的强制面;CONTRIBUTING/AGENTS 陈述与新门禁相反("bug 修复不用写"正是放走三例的判据)——与代码矛盾的文档比没有更糟。字节级二坑(工具具象化 \0 为裸 NUL 被 grep binary 报警抓住、glob 星杠提前关 JSDoc)已录入源码注释。

新立 #3766(en-drift 门禁同型 explicit-base 静默漏接缺陷——dev 在自己门禁里修掉后回头审邻居,方法正确)+ #3767(scripts/README 整页虚构,#3724 同形)入分诊池。

---

Generated by Claude Code