changelog-generator

Changelog Generator

Tier: POWERFUL
Category: Engineering
Domain: Release Management / Documentation

Overview

使用此 Skill 可根据 Conventional Commits 生成一致且可审计的发布说明。它将提交解析、语义化版本升级逻辑与变更日志渲染分离，使团队能够自动化发布，同时保留编辑控制权。

Core Capabilities

• 依据 Conventional Commit 规则解析提交信息
• 从提交流中检测语义化版本升级类型（major、minor、patch）
• 渲染 Keep a Changelog 分节（Added、Changed、Fixed 等）
• 从 git 区间或提供的提交输入生成发布条目
• 通过专用的 linter 脚本强制提交格式
• 支持以机器可读的 JSON 输出进行 CI 集成

When to Use

• 发布版本标签之前
• 在 CI 中自动生成发布说明时
• 在 PR 检查中阻止格式无效的提交信息时
• 在单体仓库中，包的变更日志需要按范围过滤时
• 将原始 git 历史转换为面向用户的说明时

Key Workflows

1. Generate Changelog Entry From Git

python3 scripts/generate_changelog.py \
  --from-tag v1.3.0 \
  --to-tag v1.4.0 \
  --next-version v1.4.0 \
  --format markdown

2. Generate Entry From stdin/File Input

git log v1.3.0..v1.4.0 --pretty=format:'%s' | \
  python3 scripts/generate_changelog.py --next-version v1.4.0 --format markdown

python3 scripts/generate_changelog.py --input commits.txt --next-version v1.4.0 --format json

3. Update CHANGELOG.md

python3 scripts/generate_changelog.py \
  --from-tag v1.3.0 \
  --to-tag HEAD \
  --next-version v1.4.0 \
  --write CHANGELOG.md

4. Compute the Next Version From Commits

当用户尚未确定下一个版本时，应据提交推导，而不是凭猜测：

git log v1.3.0..HEAD --oneline | \
  python3 scripts/version_bumper.py --current-version 1.3.0 --output-format json

输出的 JSON 包含 recommended_version、bump_type（major/minor/patch/none），以及在使用 --include-commands 时输出的确切 git tag 命令。将 recommended_version 传入 generate_changelog.py --next-version。预发布版本：添加 --prerelease alpha|beta|rc。输入必须是真实的 git log --oneline 输出（十六进制哈希）；示例文件位于 assets/sample_git_log.txt。

5. Lint Commits Before Merge

python3 scripts/commit_linter.py --from-ref origin/main --to-ref HEAD --strict --format text

或使用文件/stdin：

python3 scripts/commit_linter.py --input commits.txt --strict
cat commits.txt | python3 scripts/commit_linter.py --format json

Conventional Commit Rules

支持的类型：

• feat、fix、perf、refactor、docs、test、build、ci、chore
• security、deprecated、remove

破坏性变更：

• type(scope)!: summary
• 页脚或正文包含 BREAKING CHANGE:

SemVer 映射：

• 破坏性变更 -> major
• 非破坏性的 feat -> minor
• 其他全部 -> patch

Script Interfaces

• python3 scripts/generate_changelog.py --help
  • 从 git 或 stdin/--input 读取提交
  • 渲染 Markdown 或 JSON
  • 可选地原地前置写入变更日志
• python3 scripts/commit_linter.py --help
  • 校验提交格式
  • 在 --strict 模式下出现违规时返回非零退出码

Common Pitfalls

1. 将合并提交信息与发布提交解析混在一起
2. 使用无法转化为发布说明的模糊提交摘要
3. 未为破坏性变更提供迁移指引
4. 将 docs/chore 变更视为面向用户的功能
5. 覆盖历史变更日志章节，而不是前置追加

Best Practices

1. 保持提交小而意图明确。
2. 在多包仓库中为提交信息添加范围（feat(api): ...）。
3. 在 PR 流水线中强制执行 linter 检查。
4. 发布前审阅生成的 Markdown。
5. 仅在变更日志生成成功后才打发布标签。
6. 需要时保留一个 [Unreleased] 分节，用于人工整理。

Hotfix Severity & SLAs

发布出现问题时，先进行分级再行动（完整流程见 references/hotfix-procedures.md）：

Severity	Definition	SLA	Approval
P0 — Critical	Outage, data loss, exploited vulnerability	Fix deployed ≤ 2h; emergency deploy bypasses normal gates	Engineering Lead + On-call Manager
P1 — High	Major feature broken, significant user impact	Fix deployed ≤ 24h; expedited review	Engineering Lead + Product Manager
P2 — Medium	Minor issues, limited impact	Next release cycle	Standard PR review

Hotfix 分支从最近一次稳定标签切出，仅包含最小修复，并通过上述流程生成其自身的 patch 版本变更日志条目。

回滚触发条件

在打标签之前就预先确定以下阈值；任一条件触发时即回滚：

触发条件	阈值
错误率激增	30 分钟内超过基线的 2 倍
性能下降	延迟增加超过 50%
功能故障	核心功能失效
安全事件	漏洞正在被利用
数据损坏	数据库完整性受损

优先通过功能开关关闭功能，而不是回滚代码；仅对非破坏性迁移执行数据库回滚（优先采用仅向前的迁移）。参见 references/hotfix-procedures.md。

参考资料

• references/ci-integration.md
• references/changelog-formatting-guide.md
• references/monorepo-strategy.md
• references/hotfix-procedures.md
• README.md

发布治理

为保证发布的可预测性，请遵循以下发布流程：

1. 检查目标发布范围内的提交历史是否合规。
2. 根据提交记录生成变更日志草稿。
3. 手动调整措辞，确保对客户清晰易懂。
4. 验证语义化版本（semver）升级建议。
5. 仅在变更日志获得批准后才打发布标签。

输出质量检查

• 每条要点都应对用户有意义，而非实现层面的噪音。
• 破坏性变更必须附带迁移操作说明。
• 安全修复应单独放在 Security 节中。
• 没有条目的节应省略。
• 删除跨节重复的要点。

CI 策略

• 对所有 PR 运行 commit_linter.py --strict。
• 对不符合 Conventional Commits 规范的提交阻止合并。
• 推送标签时自动生成发布说明草稿。
• 在主分支上写入 CHANGELOG.md 前，需要人工审批。

Monorepo 指南

• 优先使提交的 scope 与包名保持一致。
• 发布特定包时，按 scope 过滤提交记录。
• 全局基础设施相关的变更保留在根目录的变更日志中。
• 将各包的变更日志存放在包根目录附近，以明确归属。

失败处理

• 若未找到有效的 Conventional Commits 提交：尽早失败，不生成误导性的空白说明。
• 若 git 范围无效：在错误输出中明确显示该范围。
• 若写入目标缺失：创建安全的变更日志头部脚手架。