Skip to content

docs(AGENTS): release workflow gains the release-notes entry step (#1870) - #1877

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-01_agents-md-release-notes-step
Oct 2, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-01_agents-md-release-notes-step

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Companion to #1873: AGENTS.md §5 documented the release flow before release-notes existed, so an agent following only AGENTS.md would miss the entry and trip the new dispatch/publish gates.

  • §5 standard flow: new step 4 'Add the release-notes entry' — same release PR, own commit (one-version-one-commit preserved), tier semantics, ≤400-char model-written summary, never hand-edit the companion package's own version. Steps 4–8 renumbered 5–9 ('steps 1–5 / step 6' references updated).
  • One-click fast path: prerequisite paragraph — the entry must be merged to master BEFORE dispatching (the workflow aborts at dispatch time otherwise; prereleases exempt), and the drift-guard list item now mentions the check.
  • Full rules stay in release-notes/README.md (from feat: tiered release-notes visibility (#1870) #1873); AGENTS.md only carries the operational step.

Docs-only; no code paths touched. Can merge in either order relative to #1873 — but merging #1873 first means the gate is live the moment this doc lands.

)

§5 standard flow: new step 4 'Add the release-notes entry' (same PR, its
own commit — preserves one-version-one-commit; tier semantics; never
hand-edit the companion package version), steps renumbered 4-8 → 5-9.
One-click fast path: prerequisite paragraph (entry must be merged to
master BEFORE dispatch — the workflow aborts otherwise) + drift-guard
item mentions the check. Details live in release-notes/README.md.
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-01_agents-md-release-notes-step (eaa917b)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1874-pr.1877.1c0c4cc

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-pr1877.tgz
npm install -g package

Install instructions are refreshed on each push.

…, not the drift guard (#1877 review)

In release-manual.yml the 'Drift guard' step only does master==npm-latest,
already-published and 0.0.x-floor checks; the release-notes entry is verified
by the separate 'Verify release-notes entry (#1870)' step that follows it.
The one-click list item 1 conflated the two.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #1877 Review 结论

审查方式:拉取本 PR diff,逐条对照 companion PR #1873 的实际代码(release-manual.yml、release.yml、release-notes/README.md、release-notes/package.json)核实——不是只看 PR body 的描述。

结构化七问

  1. 是什么问题:AGENTS.md §5 还停留在旧发布流程,完全没提 feat: tiered release-notes visibility (#1870) #1873 引入的 release-notes entry 步骤——只按 AGENTS.md 操作的 agent 会漏写 entry,然后被新的 dispatch/publish 门禁卡住。
  2. 什么原因导致的:文档漂移——feat: tiered release-notes visibility (#1870) #1873 给 workflow 加了 entry 门禁,但对应文档(§5 标准流程 + one-click 快速路径)没有同步更新。无代码缺陷。
  3. 怎么修复的:标准流程新增 step 4「Add the release-notes entry」(同一发布 PR、独立 commit,保住 one-version-one-commit),原 steps 4–8 顺延为 5–9,头部「The Agent does steps 1–6, the human does step 7」同步更新;one-click 路径加 Prerequisite 段(entry 必须先合入 master 再 dispatch,prereleases 豁免),drift-guard 条目补上 entry 检查。
  4. 是否有回归问题:无。纯文档变更,零代码路径触碰。每条操作性声明都对照了 feat: tiered release-notes visibility (#1870) #1873 实际代码:tier 语义(routine 默认 / recommended 限 correctness-cache-self-heal,marketing NEVER recommended,critical→advisories)、summary ≤400 chars、newest-first cap 20 entries、companion package 的 version 永不手改(CI publish 时 bump)、one-click dispatch-time abort + 指向 release-notes/README.md、prerelease 豁免、release.yml 在 tag/publish 前 re-check——全部与 workflow 行为一致。发现的一处措辞偏差已直接修掉(见下)。
  5. 是否破坏缓存:不涉及。
  6. 是否改了设计方向:不涉及。分工清晰:AGENTS.md 只带操作步骤,完整规则留在 release-notes/README.md。
  7. 是否引入了新的配置:不涉及。

顺手修掉的小问题(独立标注 commit eaa917b3,已推到你分支):原 drift-guard item 1 写「It also rejects … and verifies the release-notes entry exists」,把 entry 检查归到了 Drift guard 步骤名下;但 release-manual.yml 里 Drift guard 实际只做 master==npm-latest / already-published / 0.0.x-floor 三项检查,entry 检查是紧随其后的独立步骤 "Verify release-notes entry (#1870)"。已改为「A separate dispatch-time step then verifies …」,让文档与代码事实对齐。如果你更想要原来的措辞,回退即可。

CI:旧 head ecb9208 除 test (windows-latest, 24) 一次 flaky 失败(已自动重试)外全绿;新 commit 触发 CI 重跑,当前 8/12 绿、4 个 test matrix job 在跑——docs-only,预期无影响。

合并顺序:如你所说两种顺序都可以;不过我确认过 master 上目前还没有 release-notes/ 目录——若本 PR 先落地,文中引用的 release-notes/README.md 会短暂不存在。建议先合 #1873,让文档落地时门禁已 live。

结论:内容准确、声明全部经代码核实、diff 干净(单文件 +37/−9,外加上面 3 行措辞修正);CI 转绿即可合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 补充:新 head eaa917b3 的 CI 已全部转绿(12/12,含此前 flaky 的 test (windows-latest, 24))。PR 处于 mergeable 状态(仅 behind master,不阻塞)。可以合并了——建议仍按上一条所说先合 #1873。

@ranxianglei
ranxianglei merged commit 6cab41b into master Oct 2, 2026
12 checks passed
@github-actions github-actions Bot mentioned this pull request Oct 2, 2026
@ranxianglei
ranxianglei deleted the 2026-10-01_agents-md-release-notes-step branch October 15, 2026 05:32
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