changelog-generator

更新日志生成器

根据 Conventional Commits 生成一致且可审计的更新日志和发行说明。解析提交消息，检测语义化版本升级级别（major/minor/patch），生成 Keep a Changelog 格式的章节，支持 monorepo 范围限定的更新日志，可集成到 CI 中自动生成发行说明，并通过 linting 强制执行提交格式。将提交解析、版本升级逻辑和渲染分开，让团队能够自动化发布流程，同时保留编辑控制权。

关键词

更新日志，发行说明，Conventional Commits，语义化版本控制，semver，Keep a Changelog，提交 linting，发布自动化，monorepo 更新日志

核心功能

• 提交解析 — 将 Conventional Commit 消息解析为结构化数据（类型、范围、描述、正文、页脚）；从 ! 和 BREAKING CHANGE: 中检测破坏性变更。
• 语义化版本检测 — 将提交类型映射为版本升级级别（破坏性变更→major，feat→minor，其他→patch）；支持预发布版本。
• 更新日志渲染 — 按类型分组，输出 Keep a Changelog、GitHub 发行说明、纯 Markdown 和 JSON 格式。
• 质量保障 — 为 CI 和 pre-commit 钩子提供提交消息 linter，支持严格模式、范围验证和破坏性变更文档要求。

适用场景

• 发布版本标签之前
• 在 CI 中自动生成发行说明
• 在 PR 检查中强制执行提交消息规范
• 在需要按范围筛选软件包更新日志的 monorepo 中
• 将原始 git 历史转换为面向用户的说明
• 作为预发布检查清单步骤

请先确认

生成更新日志之前，请确认以下输入。如果任何信息未知或含糊不清，请提问 — 不要自行假设：

• 提交范围 — 从哪个标签或提交开始（决定纳入哪些历史记录）
• 输出格式 — Keep a Changelog、GitHub 发行说明、纯 Markdown 或 JSON（设置 changelog_formatter.py --format）
• 版本和范围 — 发行版本，以及在 monorepo 中要筛选的软件包范围（设置 --version 和范围筛选）

停止规则：只询问最可能影响输出的 2-3 项。如果用户说“直接起草即可”，就继续处理，并在产物顶部列出假设。

工具

工具	用途	命令
commit_parser.py	将 git log（使用 ---COMMIT_END--- 分隔符）解析为结构化更新日志条目	git log --pretty=format:'%H%n%s%n%b%n---COMMIT_END---' --no-merges | python scripts/commit_parser.py --json
breaking_change_detector.py	扫描提交消息/差异，查找破坏性变更标记	python scripts/breaking_change_detector.py -f gitlog.txt --severity high
changelog_formatter.py	将解析后的提交格式化为 Keep a Changelog 或 GitHub Markdown	python scripts/changelog_formatter.py -f parsed.json --version 1.4.0 --format keepachangelog

参考资料

加载与任务匹配的参考资料 — 保持此文件简洁，按需查阅详细内容：

• references/commit-format-and-rendering.md — Conventional Commit 语法、类型→章节/semver 映射表、破坏性变更规则，以及 Keep a Changelog 和 GitHub Release Notes 输出格式。定义提交规范或输出样式时阅读。
• references/generation-and-linting.md — 包含 Python 代码的 4 步 parse→bump→render 工作流、pre-commit 钩子和 CI commitlint 配置、monorepo 范围限定的更新日志策略，以及发布工作流集成图。构建流水线或强制执行格式时阅读。
• references/quality-and-troubleshooting.md — 发布前质量检查清单、常见陷阱、最佳实践、故障排除表和成功标准。发布更新日志之前或排查问题时阅读。

范围与限制

此技能涵盖：

• 将 Conventional Commit 消息解析为结构化数据，以生成变更日志
• 根据提交历史确定语义化版本升级级别（major/minor/patch）
• 以 Keep a Changelog、GitHub Release Notes、纯 Markdown 和 JSON 格式生成变更日志
• 通过 pre-commit 钩子和 CI lint 检查强制执行提交消息规范

此技能不涵盖：

• 实际的发布或部署流水线执行——请参阅 engineering/ci-cd-pipeline-design
• Git 标签管理、分支策略或合并工作流——请参阅 engineering/git-workflow-automation
• 编写或改进提交消息本身——请参阅 standards/git/git-workflow-standards.md
• 使用 Changesets 或 Lerna 等工具协调多个包的版本管理——单仓库策略中有所提及，但此处未实现

集成点

技能	集成方式	数据流
engineering/ci-cd-pipeline-design	变更日志生成作为 CI 阶段，在发布前运行	解析后的提交和生成的变更日志作为构建产物进入发布流水线
engineering/git-workflow-automation	提交 lint 钩子在提交到达变更日志生成器前强制执行格式规范	pre-commit 验证确保只有可解析的提交会进入 git 历史记录
engineering/code-review-automation	PR 检查会在合并前验证提交消息是否符合 Conventional Commits 规范	Lint 检查结果作为 PR 批准的门槛，防止无法解析的提交进入 main
engineering/api-versioning-strategy	破坏性变更检测使 API 版本升级与变更日志中的 major 版本发布保持一致	BREAKING CHANGE 提交会同时触发变更日志条目和 API 版本升级
project-management/release-management	发布规划使用生成的变更日志与利益相关者沟通	生成的发布说明会用于发布检查清单和利益相关者公告
standards/git/git-workflow-standards.md	提交格式标准定义了此技能解析的语法	标准定义是提交正则表达式模式的权威依据