更新日志生成器

Changelog Generator (变更日志生成器)

级别： POWERFUL
类别： Engineering (工程)
领域： Release Management / Documentation (发布管理 / 文档)

概述

使用此技能基于 Conventional Commits 生成一致且可审计的发布日志。它将提交解析、语义化升级逻辑和日志渲染分离，使团队能够在不丧失编辑控制权的情况下实现自动化发布。

核心能力

• 使用 Conventional Commit 规则解析提交信息

• 从提交流中检测语义化升级类型 (major, minor, patch)

• 渲染 Keep a Changelog 标准章节 (Added, Changed, Fixed 等)

• 根据 git 范围或提供的提交输入生成发布条目

• 通过专用 linter 脚本强制执行提交格式

• 通过机器可读的 JSON 输出支持 CI 集成

使用场景

• 发布 release 标签之前

• 在 CI 过程中自动生成发布日志

• 在 PR 检查期间拦截不符合格式的提交信息

• 在需要对包变更日志进行范围过滤的 monorepo 中

• 将原始 git 历史转换为面向用户的日志时

关键工作流

1. 从 Git 生成变更日志条目

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

2. 从标准输入/文件输入生成条目

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. 更新 CHANGELOG.md

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

4. 根据提交计算下一个版本

当用户尚未决定下一个版本时，通过推导而非猜测来确定：

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)

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

或使用文件/标准输入：

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

Conventional Commit 规则

支持的类型：

• feat, fix, perf, refactor, docs, test, build, ci, chore

• security, deprecated, remove

破坏性变更 (Breaking changes)：

• type(scope)!: summary

• 页脚/正文包含 BREAKING CHANGE:

SemVer 映射：

• breaking -> major

• non-breaking feat ->

• 其他所有情况 -> patch

脚本接口

• python3 scripts/generate_changelog.py --help

• python3 scripts/commit_linter.py --help

常见陷阱

1. 将合并提交（merge commit）消息与发布提交解析混淆
2. 使用过于模糊的提交摘要，导致无法转化为发布日志
3. 破坏性变更（breaking changes）缺少迁移指南
4. 将文档/琐事（docs/chore）变更视为面向用户的特性
5. 覆盖历史变更日志部分而非前置插入

最佳实践

1. 保持提交粒度小且意图明确。
2. 在多包仓库中使用提交范围（如 feat(api): ...）。
3. 在 PR 流水线中强制执行 linter 检查。
4. 发布前审核生成的 markdown 内容。
5. 仅在变更日志生成成功后才打发布标签（tag）。
6. 保留 [Unreleased] 部分以便在需要时手动维护。

热修复级别与 SLA

发布出现问题时，请先分类再行动（详细流程见 references/hotfix-procedures.md）：

| 级别 | 定义 | SLA | 审批人 |
|---|---|---|---|
| P0 — 紧急 | 服务中断、数据丢失、漏洞被利用 | ≤ 2h 完成修复部署；紧急部署可跳过常规审核 | 工程主管 + 值班经理 |
| P1 — 高 | 主要功能损坏，用户影响显著 | ≤ 24h 完成修复部署；快速审核 | 工程主管 + 产品经理 |
| P2 — 中 | 次要问题，影响范围有限 | 下一个发布周期 | 标准 PR 审核 |

热修复分支应基于最后一个稳定标签创建，仅包含最小化修复，并通过上述工作流在变更日志中记录 patch 版本升级。

回滚触发条件

在打标签前预设以下阈值；一旦触发任何一项，立即回滚：

| 触发项 | 阈值 |
|---|---|
| 错误率激增 | 30 分钟内 > 基准值的 2 倍 |
| 性能下降 | 延迟增加 > 50% |
| 功能失效 | 核心功能损坏 |
| 安全事件 | 漏洞被利用 |
| 数据损坏 | 数据库完整性受损 |

优先使用特性开关（feature-flag）禁用而非代码回滚；数据库回滚仅适用于非破坏性迁移（推荐仅向前迁移）。详见 references/hotfix-procedures.md。

参考资料

• references/ci-integration.md

• references/changelog-formatting-guide.md

• references/monorepo-strategy.md

• references/hotfix-procedures.md

• README.md

发布治理

遵循以下发布流程以确保可预测性：

1. 对目标发布范围的提交历史进行 Lint 检查。
2. 根据提交记录生成变更日志草稿。
3. 手动调整措辞以确保客户易于理解。
4. 验证 SemVer 版本升级建议。
5. 变更日志获批后方可打发布标签。

输出质量检查

• 每条记录必须对用户有意义，而非实现细节的噪音。

• 破坏性变更必须包含迁移操作。

• 安全修复需独立放在 Security 部分。

• 无条目的部分应予以省略。

• 删除跨部分的重复记录。

CI 策略

• 对所有 PR 运行 commit_linter.py --strict。

• 拦截不符合 Conventional Commits 规范的合并。

• 在推送标签时自动生成发布日志草稿。

• 写入 CHANGELOG.md 前必须经过人工审核。

Monorepo 指南

• 提交范围（commit scopes）优先与包名保持一致。

• 通过范围过滤提交流，以实现特定包的发布。

• 基础设施级别的变更记录在根目录的 changelog 中。

• 包的 changelog 存储在各自的包根目录下，以明确所有权。

错误处理

• 若未找到有效的约定式提交（conventional commits）：立即报错，不要生成误导性的空日志。

• 若 git 范围无效：在错误输出中明确显示该范围。

• 若写入目标缺失：创建安全的 changelog 标题脚手架。