用途
release-herald 面向需要为自己仓库撰写发布说明(release notes)的场景。它从使用者的视角出发,先说明用户必须变更的内容,再介绍新功能,最后列出其余变更,帮助产出一份可据以行动的发布说明。
主要能力
- 通过 gh 收集两个版本之间的全部变更集,不直接操作 git。
- 对 PR 描述和提交信息进行质量评级(empty / thin / adequate / rich),并给出摘要供撰写使用。
- 识别破坏性变更、配置变更、弃用、安全(CVE/GHSA)、文档等信号,并附带用户面文件的 diff。
- 提供 check 命令校验草稿,publish 命令可创建(默认草稿)或更新 GitHub Release。
- 支持 trunk 与 gitflow 两种流程,自动识别发布 PR 并选择更合适的比较范围。
使用方式
脚本位于 scripts/herald.py,常用命令:
python3 $S/scripts/herald.py repo [--repo HOST/OWNER/REPO] python3 $S/scripts/herald.py setup python3 $S/scripts/herald.py setup --accept <proposal.toml> python3 $S/scripts/herald.py collect --tag v1.2.0 python3 $S/scripts/herald.py check <draft.md> --tag v1.2.0 [--dropped 12,15] python3 $S/scripts/herald.py publish --tag v1.2.0 --notes-file <draft.md> python3 $S/scripts/herald.py explain
流程为:解析仓库 → 首次配置(提出流程、用户面文件、制品目的地,需用户确认)→ collect 收集并报告信号质量 → 依据摘要起草 → check 校验 → 向用户展示说明与元信息 → 仅在用户要求时 publish。
适用场景
适用于仓库维护者为新标签撰写 GitHub Release 说明,尤其关注破坏性变更、配置迁移与制品发布信息的项目。
限制
- 不编造任何变更、迁移步骤或版本号;信息不足时会明确提示。
- 不会主动打标签、升版本、推送或发布;publish 默认生成草稿,--live 需用户明确同意。
- publish 要求标签已存在于远程,不会创建标签。
- 无法读取保存在 secret 中或由任务运行器发布的制品目的地,需用户提供。
- 网络仅通过 gh 访问仓库自身主机,不联系包注册表。
- 路径采用 Linux 布局,可用 XDG 环境变量覆盖。