Release Changelog Update
Businessrelease-changelog-updateRelease Changelog Update is an Agent Skill for business published in the afkT/DevUtils repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
依据目标库/模块既有 CHANGELOG.md 版式,从上一版日期到当前用 git 收集该库根路径下 提交(含完整 commit message 正文),去重合并后撰写专业变更条目;与项目发版版本 配置对齐。在用户要求更新 CHANGELOG、发版说明、模块变更记录或同步某子库 Change Log 时使用。
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/afkT/DevUtils/blob/HEAD/.cursor/skills/release-changelog-update/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/release-changelog-update, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
发版 CHANGELOG 更新
适用范围
- 目标为库根目录(或子模块根目录)下的
CHANGELOG.md;若源码分布在多个子目录但共用同一份 CHANGELOG,则以该 CHANGELOG 所在目录为库根,git 范围覆盖所有属于该库的源码路径。 - 不得臆造版式:先 Read 目标文件顶部若干版本块,严格沿用该文件既有「Change Log」标题、下划线、
Version行、分隔线长度、条目前缀与历史语气。
文件版式(与现有一致)
Change Log
==========
Version <版本字符串> *(yyyy-MM-dd)*
----------------------------
* `[标签]` 中文说明(可含英文类名、方法名,与同文件历史条目一致)
- 标签:只使用该文件或同仓库其它 CHANGELOG 中已出现过的标签,例如
`[Add]`、`[Delete]`、`[Update]`、`[Refactor]`、`[Move]`、`[Feature]`、`[Build]`、`[Chore]`、`[Upgrade]`、`[Fix]`、`[Merge]`、`[Remove]`、`[Perf]`、`[Style]`、`[sync]`等;禁止自造未在仓库中出现过的标签缩写。 - 一条一事:同类改动合并为一条;禁止把每个 commit 机械抄成一条;语义重复的条目合并后只保留一条表述。
新版本号
- 默认以发版为准:新版本字符串以项目约定的发版版本源为准(如 Gradle/Maven/npm 等模块版本字段,与对外发布号一致)。用户或发版流程另有指定时以指定为准。
- CHANGELOG 与发版配置不同步(例如 CHANGELOG 仍为
2.5.1-2而版本配置已为2.5.2):写入 CHANGELOG 的Version必须与本次对外发布版本一致;若仅文档滞后,应对齐当前发版配置中的值并在同次提交中避免长期分叉。 - 带连字符后缀的版本(如
2.5.1-2):下一版以维护者与发版版本源为准,不臆造 semver;常见情况是下一正式补丁版为2.5.2、2.5.3等,以发版配置为准。 - 日期:
*(yyyy-MM-dd)*使用写入当天(对话中 authoritative date)或用户指定的发版日。
变更时间窗与 git 范围
- 时间基准:读取 CHANGELOG 最上方已发布版本的
Version … *(yyyy-MM-dd)*,取其中日期作为「上一版发布日」。 - 收集区间:从该日期的 00:00 起至当前(以归纳时的仓库
HEAD与对话日期为准),落在该库根目录下的改动;以 git 事实 为准,禁止写入未触及该路径的条目。 - 当日边界:若上一版当日仍有后续提交、或与「更新 CHANGELOG 的 commit」重复,可改用
--after="yyyy-MM-dd"或定位「写入上一版 CHANGELOG 的 commit」之后继续git log,减少重复;默认--since="yyyy-MM-dd"与用户约定一致即可。
必须使用「完整」commit message(勿只看第一行)
禁止仅用 git log 的 subject(%s)作为唯一依据;正文(body)、多段落说明、列表同样参与归纳。
推荐在库根路径下执行(将日期、路径替换为实际值;PATH 为库目录,如 <库根>/):
# 完整提交说明:%B = subject + body(含空行与多段)
git log --since="yyyy-MM-dd" --pretty=format:"%h%n%B%n----COMMIT----" -- PATH
# 需要作者日期辅助核对时(仍含完整 %B)
git log --since="yyyy-MM-dd" --pretty=format:"%h %ad%n%B%n----COMMIT----" --date=short -- PATH
- Merge commit:若
--no-merges后信息量足够,可忽略 merge 噪声;若重要合并说明仅在 merge message 中,则保留并去重其与子提交的重复表述。 - 多路径库:
--后写多个路径,或分路径git log后合并同一主题的 commit,条目仍按「一条一事」归纳。
归纳、去重与文案
- 通读:按时间或逆序阅读每个 commit 的完整
%B(含 body、续行、列表)。 - 去重:同一问题多次提交、revert 再修、相同类名/方法名反复出现 → 合并为一条用户向说明;忽略完全重复的句子或同一改动的 cherry-pick 副本。
- 映射标签:按真实语义选
[Fix]/[Add]/[Refactor]等,与同文件历史用法一致;不确定时优先与同库近期条目风格一致。 - 专业准确:技术事实与类/方法/模块名与仓库一致;说明用简短中文,必要时保留英文标识符。
- 插入位置:新版本块插在
==========之后、上一版Version块之前(全文从新到旧)。
变更很少或几乎无实质改动时
- 不得编造未发生的 API/功能说明。
- 参照该库 CHANGELOG 历史:许多子库在仅依赖升级或同步发版时会写
`[Chore]` 依赖 xxx 库同步升级(或对应依赖库名),句式与同文件历史保持一致。 - 若区间内确无落在该路径的提交:向用户说明「无新 commit 可记」;若发版流程仍需新版本号与日期,可仅更新
Version行与一条与历史一致的[Chore](须与发版配置/实际依赖变更一致,不得虚构依赖升级)。
版本号来源(与库根对应)
- 优先使用用户指定的版本字符串或发版版本配置文件中的对应模块字段(Gradle
versionName/version、Mavenversion、npmversion等)。 - 若用户未指明路径,在工作区内检索与目标模块/库名相关的版本声明(模块构建脚本、根版本清单、CI 发版变量等),不得臆造版本键名或版本号。
- 写入 CHANGELOG 的
Version必须与本次对外发布版本一致;多子模块各自 CHANGELOG 时,每条记录对其库根的版本源,勿混用其它模块版本。
执行清单
- Read 目标
CHANGELOG.md顶部 2~3 个版本块,确认标题、标签、句式。 - 解析上一版
Version … *(yyyy-MM-dd)*与即将写入的新版本(对照发版版本源或用户指定)。 - 对该库路径执行
git log,格式含完整%B,必要时配合git diff/git show核对事实。 - 合并去重后撰写条目;少变更时对齐历史
[Chore]等写法。 - 在文件顶部插入新版本块,不破坏下方历史结构。