常规提交变更日志构建器技能

--- name: conventional-commits-changelog-builder description: 将符合 Conventional Commits 格式的 git log 转换为可直接粘贴的 Keep a Changelog 发布章节 - 包含 Added、Changed、Deprecated、Removed、Fixed、Security - 带有作用域、问题和提交链接以及破坏性变更块。标记没有迁移说明的破坏性变更、不符合规范的提交和 fixup 提交、还原和重复项，并建议下一个 SemVer 版本。包含一个离线的 stdlib Python 构建器，支持 --self-test。 --- # Conventional Commits Changelog Builder 你帮助维护者将自上次标签以来的提交转换为人们真正能读懂的变更日志条目。手动编写意味着滚动日志、猜测哪些提交重要，并遗漏隐藏在页脚中的破坏性变更。盲目生成会复制每个拼写错误、WIP 提交和已还原的功能到发布中。你解析提交，将它们映射到 Keep a Changelog 章节，准确列出遗漏的内容及其原因，并说明发布应获得哪个版本。 ## 此技能中的文件 - `scripts/changelog_build.py` - 读取 `git log`（默认格式）、`git log --oneline` 或 `%x1f`/`%x1e` 记录导出；解析 `type(scope)!: description` 头部和 `BREAKING CHANGE:` 页脚；分组为 Added / Changed / Deprecated / Removed / Fixed / Security，并带有 BREAKING CHANGES 块；取消范围内相互抵消的还原，跳过合并，删除重复项，标记 fixup/WIP 和不符合规范的提交并建议头部；链接问题、提交和比较范围；建议 SemVer 版本提升（支持 0.x）；可以将章节插入现有的 CHANGELOG.md（仅使用 Python 3.8+ 标准库） - `references/commit-to-changelog-mapping.md` - 类型到章节的映射表、破坏性变更规则、版本提升规则以及查找代码 CC01-CC10 - `references/release-hygiene.md` - 为用户编写条目、迁移说明、如何处理不符合规范的历史记录以及 CI 检查 - `templates/release-notes-review.md` - 随章节一起返回的审查模板 - `examples/git-log.txt` - 一个虚构 CLI（tidyq）自 v2.3.1 以来的 21 个提交：两个破坏性变更、一个安全修复、一个弃用、一个还原、一个重复的 cherry-pick、一个 fixup、一个 WIP 和一个简单的“Fixed ...”提交 - `examples/CHANGELOG.md` - 项目现有的变更日志（Unreleased + 2.3.1 + 2.3.0） - `examples/changelog-report.md` - 构建器在该日志上的实际输出 ## 工作流程 ### 1. 获取提交范围 询问最后一个已发布的标签，并导出其后的所有内容，最新的在前： ``` git log v2.3.1..HEAD > commits.txt git log v2.3.1..HEAD --format='%H%x1f%s%x1f%b%x1e' > commits.txt # 最安全：保留正文，无需解析猜测 ``` 同时询问当前版本、发布日期、仓库 URL（用于链接）、标签前缀（默认为 `v`）以及是否应列出内部提交（refactor、docs、ci、chore、test）。squash-merge 工作流是理想的：一个 PR = 一个提交 = 一行。 ### 2. 运行构建器 ``` python3 scripts/changelog_build.py examples/git-log.txt --current 2.3.1 --date 2026-11-03 --repo-url https://github.com/tidyq/tidyq python3 scripts/changelog_build.py commits.txt --current 2.3.1 --insert CHANGELOG.md > CHANGELOG.new.md python3 scripts/changelog_build.py commits.txt --current 0.9.4 --include-internal --json python3 scripts/changelog_build.py --self-test ``` 退出码 0 = 可以打标签，1 = 高优先级发现，2 = 输入错误。如果没有 shell，手动应用 `references/commit-to-changelog-mapping.md`：解析每个头部，将类型映射到章节，收集 `!` 和 `BREAKING CHANGE:` 页脚，取消还原，然后选择最高的版本提升。 ### 3. 在打标签前修复发现的问题 - CC03（高）：带有 `!` 但没有 `BREAKING CHANGE:` 页脚的提交没有给用户提供迁移路径。将说明（什么被破坏，应该怎么做）写入章节。 - CC08（高）：看起来像功能或修复但不符合规范的提交缺失于变更日志。使用建议的头部手动添加它们，并启用提交检查。 - CC07：fixup/WIP 提交应在发布前压缩；CC04：对旧版本的还原需要一句解释原因。 - CC01/CC02/CC05/CC06：措辞和符合性；在变更日志文本中修复，而不是重写已发布的历史。 ### 4. 为人类编辑 构建器给你正确的结构，而不是好的散文。将条目重写为用户可见的效果（“导出默认写入 Parquet”而不是“重构写入器”），合并描述同一变更的条目，保留用户能识别的作用域，并将 BREAKING CHANGES 块放在没人能错过的地方。参见 `references/release-hygiene.md`。 ### 5. 交付 填写 `templates/release-notes-review.md`：版本及其原因、最终章节、迁移说明、遗漏的内容以及后续事项（commitlint、PR 标题检查）。使用 `--insert` 时，返回更新后的 CHANGELOG.md；原始文件永远不会被修改。 ## 示例结果 在 `examples/git-log.txt`（当前 2.3.1）上，构建器读取 21 个提交，85% 符合规范，并建议 **3.0.0**：`feat(export)!` 使 Parquet 成为默认格式（带有正确的 BREAKING CHANGE 页脚），`fix(config)!` 删除了 INI 配置文件但没有迁移说明（CC03，高）。“Fixed crash when the config file is empty” 不是 Conventional Commit，会静默遗漏在变更日志中（CC08，高；建议 `fix: crash when the config file is empty`）。令牌泄露修复归入 Security，`--legacy-dates` 弃用归入 Deprecated，颜色主题功能及其还原相互抵消，cherry-picked 的 BOM 修复只列出一次，合并、fixup、WIP 和 5 个内部提交被列为遗漏。 ## 规则 - 绝不发明条目：每一行都来自一个提交，每个提交要么在章节中，要么在“遗漏”列表中。 - 破坏性变更总是获得迁移说明和主版本提升（在 0.x 上为次版本）；绝不隐藏在 Changed 中。 - 安全修复归入 Security，即使提交类型是 `fix`。 - 不要重写已发布的历史来修复提交消息；修复变更日志文本并为未来添加检查。 - 保持最新发布在最上面，日期格式为 YYYY-MM-DD，每个版本一个比较链接。 - 版本是建议：维护者决定，尤其是对于类型为 `fix` 的行为变更。