Skip to content

ci(release-notes): PR-time payload guard — hold the 400-char cap BEFORE merge - #2820

Open
ranxianglei wants to merge 4 commits into
masterfrom
fix/release-notes-guard
Open

ranxianglei wants to merge 4 commits into
masterfrom
fix/release-notes-guard

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Why

The 400-char summary cap (and the rest of the payload contract) is only enforced by the Publish Release Notes workflow — which runs after merge (push to master + release-notes/** paths filter). It can never hold a PR, so over-cap entries could only fail one step too late:

What

file change
scripts/release-notes-guard.mjs new zero-dep validator; same rules, same verbatim error messages; optional path arg
.github/workflows/ci.yml new release-notes-guard job (config-surface-guard posture: checkout + node, no install step) — the PR-time interceptor
.github/workflows/release-notes.yml inline validator replaced by a call to the script — one copy of the contract
tests/release-notes-guard.test.ts 10 unit tests: real payload golden anchor + planted violations (401 cap, inclusive 400, bilingual 丨 shape, bad tier, dup, bad semver, bad date, >20 entries, schema shape)
scripts/release-notes-guard.d.mts declarations for the test import

Verification

  • node scripts/release-notes-guard.mjs → 14 entries ok; planted 520-char summary → exit 1 with the exact original message
  • node --import tsx --test tests/release-notes-guard.test.ts → 10/10 pass
  • npm run typecheck → clean; both workflow YAMLs parse

Risk

Zero runtime surface touched — CI/workflow/doc files only.

…RE merge

The Publish Release Notes validator only runs after merge (push to master
+ paths filter), so it can never hold a PR; over-cap entries failed one
step too late — runs 38040163381 (0.1.191: 401 chars) and 38152721758
(0.1.192: 520 chars), fixed in #2818.

- scripts/release-notes-guard.mjs: zero-dep validator (same rules, same
  verbatim error messages), callable from both workflows
- ci.yml release-notes-guard job (config-surface-guard posture: plain
  node, no install step) — the actual PR-time interceptor
- release-notes.yml now calls the script; the inline copy is gone
- tests/release-notes-guard.test.ts: unit teeth — planted violations
  (over-cap, inclusive-400, bilingual shape, bad tier, dup, bad semver,
  bad date, >20 entries, schema) must turn the guard red, not vacuous
@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: fix/release-notes-guard (aa196ac)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3128-pr.2820.63e1198

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr2820.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 进行中(中间报告)

方向已核实:400-char cap 此前只在 merge 后的 Publish Release Notes workflow 强制(run 38040163381 / 38152721758 两次实锤),PR-time 拦截是真实缺口。本地已定向验证:脚本对当前 payload 输出 14 entries ok、单测 10/10、新旧校验规则逐条比对无回归。

CI 在 head bf0c7aae 上红了一处,已本地复现:unused-exports 门禁标记 scripts/release-notes-guard.d.mts 的两个 doc-only interface(ReleaseNotesEntry INTERNAL_ONLY、ReleaseNotesPayload DEAD)。另有两处小问题(模块末尾无条件 main() 导致测试 import 有副作用;双语形状测试注释写 "400 exactly" 实际 399 字符)。

三处都是 PR 引入文件内的小修,按「小问题直接修」正在 PR 分支上补 commit(独立标注),push 后等 CI 转绿再给八问结论。

ework-agent added 2 commits October 12, 2026 00:20
…tion

main() ran on module load, so importing validateReleaseNotesPayload in tests printed the ok-line (and would process.exit(1) at import time if the payload were invalid, killing the test child before any test ran). Gate main() behind a direct-invocation check; CLI behavior unchanged.
The comment claimed '400 exactly' but 196+3+200 = 399. Bump to 197 so the test actually exercises the inclusive boundary in the bilingual 丨 shape.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 完成 — 结论:可合并(head aa196ac8b,CI 15/15 全绿,含此前红的 unused-exports)

① 是什么问题:release-notes payload 的 400-char cap(及整份契约)只在 Publish Release Notes workflow 强制,而该 workflow 由 push-to-master + paths filter 触发,结构上拦不住 PR——超限条目只能 merge 后在发布步骤失败(run 38040163381 / 38152721758 两次实锤)。

② 什么原因导致的:不是代码 bug,是守卫放置位置缺失——ci.yml(PR-time)侧没有对应校验,唯一一份校验器内联在 post-merge workflow 里。因果分层:根因=契约执行点晚于拦截点;表象=merge 后发布步骤红、需要追加修复 commit(#2818)。

③ 影响范围与严重程度:所有改 release-notes/package.json 的 release PR;严重度=流程/体验级——最坏情况是 merge 后发布步骤失败再补一刀,无运行时影响。

④ 怎么修复的:把内联校验器抽成零依赖脚本 scripts/release-notes-guard.mjs(错误消息逐字保留),ci.yml 新增 release-notes-guard job 做 PR-time 拦截,release-notes.yml 改为调用同一脚本——契约收敛为一份拷贝。我的 review 小修(已在分支上补 commit):.d.mts 两个 doc-only interface 去掉 export(unused-exports 门禁红→绿,同 config-surface-guard.d.mts 先例)、模块末尾 main() 加直接调用判定(测试 import 不再产生副作用/提前 exit)、双语形状测试 399→恰好 400 字符(注释与断言一致)。说明:门禁那处另一个并行会话已推了内容相同的 commit(93d4add78),我 rebase 时丢弃了自己的重复提交,最终 head = 原 commit + 3 个小修。

⑤ 是否回归问题:逐条比对了旧内联校验器 vs 新脚本的全部规则,有效 payload 的接受/拒绝行为不变。有意的诊断性变更(披露旧→新):a) 报错从 fail-fast 第一条 → 收集全部错误仍 exit 1; b) semver 校验从 npm semvalid → 实用正则(对 01.2.3 这类前导零输入更宽松;payload 实际只承载纯 release tag,且现在两处调用点共用同一实现,跨点一致性反而变强); c) payload 文件不可读从 uncaught throw → 干净的 cannot-read 消息 exit 1; d) 路径解析从 cwd 相对 → repo-root 相对,并支持可选 path 参数。高危模式逐项过:无 fail-fast 变吞错(exit code 语义未动)、无阈值漂移(cap 仍是 400)、无输出格式变化(消息逐字保留)。

⑥ 是否破坏缓存:不涉及(CI/workflow 文件,无缓存/重试/游标/去重键)。

⑦ 是否改了设计方向:不涉及架构转向;只是把同一契约的执行点前移到 PR-time 并去重为单拷贝。

⑧ 是否引入新配置:无——没有新 env/config/flag;CI job 名 release-notes-guard 不构成用户面配置。

本地定向验证:check-unused-exports clean、CLI 14 entries ok、import 无副作用、单测 10/10;merge-tree 对当前 master 无冲突。建议直接合并。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant