SuperAPI AI 工具集

release-herald

编程与开发

查看项目

更新于 11-09 04:27

技能介绍

用途

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 环境变量覆盖。