docs(agents),ci: release notes are release-owned, scoped re-verify, merge_group triggers - #4490
Merged
Merged
Conversation
…erge_group triggers Three multi-agent throughput fixes from one PR's merge history (#4458 went three full green CI cycles without landing — main merged 18 PRs in the same 6 hours, and two of its three conflicts were rows racing into the same release-notes table): 1. `content/docs/releases/` is RELEASE-OWNED — never edited in a code PR. Release notes are compiled centrally at release time from changesets + the ADR-0087 registries; a per-PR appended row made `releases/v<major>.mdx` the repo's hottest conflict magnet. Inlined in CLAUDE.md (the must-never-miss set), added to the AGENTS.md Documentation Guardrails table, and the spec-property-retirement skill's checklist item — the one instruction that explicitly sent agents into that file — now routes through the changeset instead. 2. AGENTS.md multi-agent §10 scopes the post-merge re-verify. The first pull-main-and-full-suite round stays. Subsequent merges done only because main moved during CI: rebuild + `check:generated` when spec moved on either side, assert the branch's delta vs main is still exactly the PR's intent, and reserve the full typecheck+test for semantic overlap or non-mechanical conflicts. CI validates the merge commit either way; a 15-minute full lap per merge is what turns a busy main into a livelock. 3. `merge_group:` triggers on the three required-check workflows (ci.yml, lint.yml, spec-liveness-check.yml), so the repo can turn on GitHub's merge queue — the race-free version of §10, run by the platform. ci.yml details: the paths filter has no merge_group support, so queue builds treat everything as changed (a skipped filter step's empty output falls back to 'true'), and the full-suite step runs on queue builds (the queue result IS the next main). §7 now names the queue as the sanctioned path once an admin enables it — the opposite of the auto-merge it bans, since the queue lands only speculatively-merged-and-green results. pr-automation and docs-drift-check are deliberately NOT queue-triggered (PR-context-bound; must not be marked required). Enabling the queue itself is a branch-protection setting only an admin can flip; this commit makes the workflows ready for it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M9uWvoEp9CoLzYjNExj9sL
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
The Check Changeset gate requires each PR to declare its release impact; the sanctioned "releases nothing" declaration is an empty-frontmatter changeset (per the gate's own inline doc), which a docs+workflow-only PR is exactly the case for. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M9uWvoEp9CoLzYjNExj9sL
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
2 participants
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.
三条多 agent 吞吐修复,依据是 #4458 的真实合并史:那个 PR 三轮 CI 全绿仍落不下去 —— 同 6 小时 main 合了 18 个 PR(高峰 5 分钟一个),而它三次冲突里有两次是各 PR 往 v17 release notes 的同一张表里抢着追加行。
1.
content/docs/releases/划为 RELEASE-OWNED,代码 PR 禁改Release notes 由发布流程统一编写,输入是 changesets + ADR-0087 registries —— 不是一个 PR 贴一行攒出来的。对照数据:
.changeset/同 6 小时新增 18 个文件、零冲突(一次改动一个文件);releases/v17.mdx一个下午被 3 个 PR 抢同一张表。content/docs/releases/行.claude/skills/spec-property-retirement/SKILL.md:唯一一处明确指示 agent 去改 releases 页的 checklist 项,改为经由 changeset —— 不改这里,规则立不住2. AGENTS.md 多 agent 纪律 §10:收窄合并后复跑范围
第一轮 pull main + 全量复跑保留。此后仅因「CI 期间 main 又动了」而做的再合并,改为:
spec build && check:generated(生成物快照是「合起来才错」的经典载体,git 的文本合并结果必须靠重建验证);断言分支相对 main 的 delta 仍恰好是本 PR 意图(如「N removed / 0 added」)3. 三个 required-check 工作流加
merge_group:触发器为开启 GitHub merge queue 做好工作流侧准备 —— 队列把每个 PR 按推测合并到当前 main 的结果跑 CI、绿了才落,正是 §10 那条纪律的平台化、无竞态版本。
'true');全量测试步骤在队列构建上走 push 路径(队列结果就是下一个 main,理应获得 main 级验证)启用 merge queue 是 branch protection 设置,本 PR 改不了 —— 操作步骤见 PR 讨论/会话记录。在管理员启用之前,本 PR 的
merge_group触发器是无害的死代码;启用之后立即生效。验证
[push, pull_request, merge_group]/[pull_request, merge_group]github.event.pull_request的全部残余用法均有安全回退(concurrency group 回退github.ref;TURBO_SCM_BASE在 PR-only 步骤内)关联:#4458(livelock 实例)、#4446
Generated by Claude Code