用途
rea-changelog-update 用于发布说明的准备与贡献者署名整理。使用前应从仓库根目录读取 docs/releasing.md,了解发布权限与现有的检查点检查。该技能只准备发布说明,不授权合并、打标签或发布。
工作流程
先盘点再撰写
先获取完整历史与标签。从发布 PR 目标分支上的 .release-please-manifest.json 中选取已发布的基线标签,并把该分支的精确 SHA 固定为编辑目标。REA 的标签格式为 rea-agents-VERSION。使用拟议版本(包含其预发布后缀),不要为了模仿 OpenClaw 的日历版本而更改 always-bump-minor 策略。
资料给出的命令示例:
node scripts/release-notes.mjs inventory \
--repository morluto/rea --base rea-agents-PREVIOUS \
--target FULL_BASE_BRANCH_SHA --version VERSION \
--manifest /tmp/rea-VERSION.contributions.json
node scripts/release-notes.mjs record \
--manifest /tmp/rea-VERSION.contributions.json \
--summary \
--output /tmp/rea-VERSION.record.md
应阅读盘点结果,而不只是查看已有的机器人草稿。盘点范围包含侧分支提交、合并提交位于区间内的 GitHub 关联 PR、提交作者/共同作者,以及已确认关联的关闭 issue 及其报告者。GitHub 关联数据是分页获取的。网络错误会中止生成,恢复后应重跑并输出到新文件;已有输出文件不会被覆盖。
无法解析的提交身份会以姓名/邮箱保留,user 为 null;不得猜测账号,也不得用合并者替代致谢。报告会保留未知项。这是经审阅的元数据快照,并非人类作者身份的独立证明。对于未归属身份、异常合并策略、回移、回滚或 GitHub 未关联的引用,应检查源 PR 和 diff 并报告该限制。当前收集器仅依据已确认的 PR 关闭关系为 issue 报告者致谢;无关的 issue 提及不会自动致谢。不得声称仅被盘点、但已在回滚后不再发布的工作仍会发布。
面向用户撰写并保留署名
只重写 CHANGELOG.md 中最新的 ## [VERSION] 段落,保留其版本/日期/链接标题。使用单行 Markdown 列表项,分为:
- Highlights:若干定义本次发布的关键用户成果;小版本无配额要求。
- Changes:能力与有意义的行为变更。
- Fixes:可靠性、正确性、兼容性和安全性修复。
- ⚠ BREAKING CHANGES:适用时保留,需含迁移说明及现有检查点校验器要求的原始 PR/提交引用。
按分析工作流或用户影响对相关工作分组。用简短、具体的条目说明最终行为。Highlights 概述发布,避免在 Changes 中重复其完整描述。内部清理、测试、CI 和常规文档一般只放入溯源文件。作出表述前应阅读含义不明的 PR/diff。区分模拟提供方检查与真实提供方验证。
每项被代表的贡献在公开说明中只致谢一次,附链接与“Thanks @...”给已验证的人类作者、已知共同作者和已确认的关闭 issue 报告者。分组时把这些致谢保留在同一行。当 Highlights、详细条目或迁移引用同一工作时,只在其中一处写致谢。包含 issue 链接。直接提交的条目附带提交链接和已知人类署名。排除 GitHub 机器人和已知 agent 账号。REA 中观察到的 Anthropic、Cursor、Codex、Copilot 共同作者尾注解析为 @claude、@cursoragent、@codex、@Copilot(GitHub 类型为 User),署名政策将其排除,但保留其元数据。按 REA 维护者要求,省略 @morluto 的自我致谢,但在盘点中保留其作者身份。其他人贡献者仍可致谢。跨仓库引用使用明确的 GitHub 链接,避免含糊的 #NNN 编号。未知账号保持未知,不得捏造署名。
将生成的记录 --summary 溯源链接按原样附在本次发布末尾。链接的盘点覆盖所有发现的区间内 PR 与直接贡献,包括从正文中省略的内部工作。不要把完整记录输出粘进公开说明,它会重复致谢并掩盖面向用户的变更;完整记录仍可供审阅。不要手工编辑生成的致谢以通过校验。产品历史变化时刷新盘点;仅正文修正可复用快照。
用 Release Please 完成定稿
在更改生效中的发布 PR 前,需获得该 PR 更新的授权。本地准备与校验可独立进行。
在编辑分支/正文前,给选定的开放发布 PR 添加 rea:release-notes-finalized 标签。主提案推送会遵守该标签。这是工作流保护,而非 Release Please 的 autorelease: snooze 机制。已在运行的提案须先完成再编辑。不得在已定稿说明上再派发手工准备。
在该发布分支上,将审阅过的盘点保存为 docs/releases/VERSION.contributions.json。这是持久的公开发布溯源,不是临时规划文件。不得添加凭据或本地环境转储。保持现有版本工件一致。
运行现有检查点校验器与新检查器:
node scripts/release-notes.mjs check \
--manifest docs/releases/VERSION.contributions.json
node scripts/release-notes.mjs render \
--manifest docs/releases/VERSION.contributions.json \
--output /tmp/rea-VERSION.notes.md
检查器支持内联 PR 正文(含周边元数据),上限为 GitHub 的 65,536 字符;超过则失败而不截断致谢;Release Please 的溢出链接正文未集成。
用渲染后的段落更新发布 PR 正文,保留其 Release Please 页眉/页脚与组件/版本结构。使用 gh pr edit --body-file 时采用正文文件;仅修改 CHANGELOG.md 不会改变 Release Please 的发布正文。只推送已授权的更改。
重新获取 PR 正文到文件并运行 check --pr-body FILE。审阅完整 diff 并等待当前 CI。发布前会再次检查正文。发布期间避免进一步编辑正文。
定稿标签冻结机器人刷新,但不冻结主分支。盘点目标之后的新产品变更需在发布前刷新说明。工作流检查目标祖先关系,并只允许该目标之后的发布元数据路径;还要求盘点目标等于所审阅合并的第一个父提交,因此中间出现的主分支提交需重新盘点。也应审阅允许的发布元数据路径内的 diff:路径保护不能证明依赖/脚本编辑仅为版本变更。要恢复自动提案,移除定稿标签让机器人重新生成;预期编辑性改动会被替换。
没有贡献盘点的既有发布保留其当前发布路径。绝不通过重新打标签或重新发布包来修正发布文案。