变更日志Skill：自动生成CHANGELOG - 学习笔记-流行Skills

一、变更日志Skill的设计

变更日志（CHANGELOG）是软件开发中至关重要的文档，它记录了项目在每个版本发布中的变更内容。然而，手动维护CHANGELOG往往容易被遗忘，导致文档滞后或内容不完整。变更日志自动生成Skill正是为了解决这一痛点而生，它能够自动从Git提交历史中提取信息，生成结构化的CHANGELOG文件，极大地减轻开发者的维护负担。

该Skill的核心设计理念包含以下几个方面：自动从Git提交历史中提取变更信息，无需开发者额外记录；统一团队的变更记录格式，遵循行业标准的Conventional Commits规范；支持按版本发布节奏自动或手动触发生成；以及提供多格式输出能力，让CHANGELOG可以嵌入到不同的平台和工具链中。

一个设计良好的变更日志自动生成Skill，应当成为项目CI/CD流水线中的一环，在每个版本发布时自动生成或更新CHANGELOG文件，确保变更历史始终与代码保持同步。

自动生成

从Git提交历史自动提取变更内容，生成结构化的CHANGELOG文件，无需手动编写

格式统一

遵循Keep a Changelog标准和Conventional Commits规范，确保团队提交记录格式统一

版本管理

根据提交类型自动计算语义化版本号，支持手动覆盖，灵活控制版本升级策略

多格式输出

支持Markdown、HTML、JSON等多种输出格式，适配不同平台和工具链需求

二、Git提交历史分析

变更日志自动生成的第一步是分析Git提交历史。Skill需要读取项目的Git log，获取从上一个版本到当前版本之间的所有提交记录，然后对每条提交进行解析和分类。

Conventional Commits规范是目前最广泛使用的提交信息格式，其基本结构为：类型(范围): 描述。常见的提交类型包括：feat表示新功能，fix表示Bug修复，breaking或!表示破坏性变更，perf表示性能改进，docs表示文档更新，refactor表示代码重构，test表示测试相关，chore表示构建或工具变更等。

在分析提交历史时，Skill需要完成以下任务：读取Git log获取指定范围内的提交记录；解析每条提交信息的类型、范围、描述和正文；识别破坏性变更标记（如提交信息中包含BREAKING CHANGE或类型后的!标记）；过滤非功能性提交（如chore、docs等可根据配置选择是否包含）；按版本tag将提交分组，便于生成按版本组织的CHANGELOG。

# 读取Git提交历史的核心命令示例
git log --oneline --format="%H %s%n%b" v1.0.0..HEAD

# 使用--grep过滤特定类型的提交
git log --oneline --grep="^feat" v1.0.0..HEAD
git log --oneline --grep="^fix" v1.0.0..HEAD

最佳实践：推荐团队统一使用Conventional Commits规范，并在CI中配置提交信息校验（如commitlint），确保每条提交都符合规范格式。这样可以大幅提升CHANGELOG自动生成的质量和准确性。

三、语义化版本号计算

语义化版本控制（Semantic Versioning，简称SemVer）是软件版本管理的行业标准，版本号格式为MAJOR.MINOR.PATCH。变更日志自动生成Skill可以根据提交历史中的变更类型自动计算下一个版本号，实现版本号管理的自动化。

版本号自动计算的规则如下：如果提交中包含破坏性变更（BREAKING CHANGE），则MAJOR版本号加1；如果有新功能（feat）提交，则MINOR版本号加1；如果只有修复（fix）和其他非破坏性变更，则PATCH版本号加1。如果提交历史为空或仅有文档、测试等不影响生产的变更，则可以跳过版本发布。

在实际使用中，Skill还应当支持以下高级策略：允许手动指定版本号以覆盖自动计算的结果；支持预发布版本号（如1.0.0-alpha.1、2.0.0-beta.2）；支持版本号前缀（如v前缀：v1.0.0）；能够在monorepo中为不同包分别计算版本号。

# 版本号自动计算逻辑（伪代码）
function calculate_next_version(current, commits):
    has_breaking = any(c.type == 'breaking' for c in commits)
    has_feat     = any(c.type == 'feat'     for c in commits)
    has_fix      = any(c.type == 'fix'      for c in commits)

    if has_breaking:
        return bump_major(current)
    elif has_feat:
        return bump_minor(current)
    elif has_fix:
        return bump_patch(current)
    else:
        return null  # 无需发布

四、CHANGELOG格式化输出

CHANGELOG的格式化输出是Skill的核心功能之一。推荐遵循Keep a Changelog标准格式，该格式已成为业界广泛采用的CHANGELOG规范。标准的CHANGELOG文件包括以下结构：文件标题和项目简介；按版本号倒序排列的变更记录；每个版本包含发布日期、变更类型分类等内容。

变更内容按照类型进行分类组织，典型的分类包括：新功能（Added）——feat提交归入此类；Bug修复（Fixed）——fix提交归入此类；破坏性变更（Changed）——breaking change提交归入此类；性能改进（Improved）——perf提交归入此类；弃用功能（Deprecated）——deprecated提交归入此类；移除功能（Removed）——removed提交归入此类；安全修复（Security）——security提交归入此类。

在输出时，Skill还应当为每条变更添加相关的上下文信息，如PR/Issue链接和贡献者信息，方便读者追溯变更的详细讨论和背景。同时支持按范围（scope）对变更内容进行二次分组，让CHANGELOG更有条理。

# CHANGELOG生成输出示例（Markdown格式）

# Changelog

## [2.1.0] - 2026-05-01

### Added
- 新增用户权限管理模块 (#245, @zhangsan)
- 支持多语言国际化功能 (#238, @lisi)

### Fixed
- 修复登录页面在移动端的布局问题 (#241, @wangwu)
- 修复文件上传超时导致的崩溃 (#237, @zhaoliu)

### Changed
- **BREAKING**: 重构API认证机制，改用JWT (#240, @zhangsan)

### Improved
- 优化数据库查询性能，响应时间降低60% (#239, @chenqi)

注意事项：CHANGELOG中应当避免包含内部开发细节、敏感信息或未完成的特性。每条变更内容应当面向读者（用户或其他开发者）描述其影响，而非仅仅复制Git提交信息。此外，建议在CHANGELOG中注明每个版本的发布日期，便于追踪版本发布历史。

五、Release Notes生成

Release Notes是面向不同受众的版本发布说明，它与CHANGELOG类似但侧重点不同。CHANGELOG是面向开发团队的完整变更历史记录，而Release Notes则更关注向特定读者传递版本的核心变化和价值。变更日志自动生成Skill可以从CHANGELOG中提取当前版本的变更摘要，生成面向不同读者的Release Notes。

面向用户的Release Notes应当语言通俗易懂，聚焦于功能变化和使用体验改进，去掉技术细节（如PR编号、内部API变更等）。面向开发者的Release Notes保留技术细节，包括API变更、依赖更新、迁移指南等。面向管理者的Release Notes侧重项目的进展和里程碑达成情况，关注交付价值和团队效率。

Release Notes的发布渠道通常包括：Slack频道通知——发布后自动推送消息到团队频道；邮件通知——发送版本发布邮件到订阅者列表；发布平台——自动发布到GitHub Releases、GitLab Releases等平台。Skill可以与这些渠道集成，实现一键发布通知。

# 面向用户的Release Notes示例
## 版本 2.1.0 发布说明

亲爱的用户，我们很高兴地宣布 v2.1.0 正式发布！

### 新功能
- 用户权限管理：现在可以为团队成员分配不同角色
- 多语言支持：界面已支持中文、英文和日文

### Bug修复
- 修复了移动端登录页面的显示问题
- 解决了大文件上传时的稳定性问题

### 性能提升
- 页面加载速度提升了约60%
- 减少了50%的内存占用

核心要点总结：变更日志自动生成Skill的核心在于：建立规范的提交习惯（Conventional Commits）是基础；自动分析提交历史并分类整理是核心能力；语义化版本计算让版本管理更科学；多格式输出满足不同场景需求；与CI/CD流水线集成实现全流程自动化。最终目标是让开发者专注于代码本身，而CHANGELOG的维护由Skill自动完成。

六、实践应用与集成

在实际项目中，变更日志自动生成Skill可以集成到多种开发工作流中。最常见的集成方式是将其作为CI/CD流水线的一个步骤，在触发版本发布时自动运行。例如，可以在GitHub Actions、GitLab CI或Jenkins中配置相应的自动化任务。

# GitHub Actions 集成示例
# .github/workflows/release.yml
name: Generate Changelog
on:
  push:
    tags:
      - 'v*'

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Generate Changelog
        run: npx changelog-generator --output CHANGELOG.md
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          body_path: CHANGELOG.md

除了CI/CD集成，该Skill还支持本地命令行使用。开发者可以在发布前在本地运行Skill预览即将生成的CHANGELOG内容，进行必要的调整和补充后再提交。这种"先预览再发布"的模式可以确保生成的CHANGELOG内容准确完整。

进阶技巧：在Monorepo项目中，可以为每个子包分别维护CHANGELOG。Skill需要识别每个提交所属的包范围（通过scope字段），然后分别为每个包生成独立的CHANGELOG文件。此外，可以结合Git标签（tag）进行版本比对，只处理与当前包相关的提交记录。

七、常用工具与资源

目前社区中有多个成熟的变更日志自动生成工具可供参考和使用：

工具名称	语言/平台	特点
standard-version	Node.js	自动版本号计算+CHANGELOG生成+Git标签管理
semantic-release	Node.js	全自动版本发布流程，支持丰富的插件生态
git-cliff	Rust	高性能、高度可配置的CHANGELOG生成器
auto-changelog	Node.js	轻量级、无需Conventional Commits也能工作
change log	Python	Python生态中的CHANGELOG生成工具

在实际构建自己的变更日志自动生成Skill时，可以借鉴这些优秀工具的设计思想和实现细节，结合自身项目的特性进行定制化开发。

八、核心要点总结

1. 设计理念：变更日志自动生成Skill的核心是"让机器做机器擅长的事"——自动分析Git提交历史，减少人工维护CHANGELOG的负担，同时保证变更记录的完整性和一致性。

2. 技术基础：Conventional Commits规范是CHANGELOG自动生成的基石，团队需要形成统一的提交信息书写习惯，这是整个自动化流程的前提条件。

3. 版本管理：语义化版本号计算实现了版本管理的自动化，基于提交类型智能推断版本升级策略，同时保留手动覆盖的灵活性。

4. 输出多样性：支持Markdown、HTML、JSON等多格式输出，适配不同使用场景——Markdown适合Git仓库、HTML适合网页展示、JSON适合程序解析。

5. 受众适配：Release Notes面向不同读者提供差异化的内容，用户关注功能变化、开发者关注技术细节、管理者关注项目进展，一份变更数据可以产出多份针对性的发布说明。

6. 流水线集成：将Skill集成到CI/CD流水线中，实现版本发布的全程自动化——从提交分析到CHANGELOG生成再到发布通知，一气呵成。

九、进一步思考

变更日志自动生成Skill的价值不仅在于节省时间，更在于建立一种规范的开发文化。当团队成员知道提交信息会被自动整理成CHANGELOG并展示给用户时，会更加注重提交信息的质量和规范性。这种正向反馈机制可以持续提升团队的工程素养。

未来可探索的方向包括：结合AI能力自动生成更友好的变更描述，而不仅仅是机械地整理提交信息；支持多仓库联合CHANGELOG生成，适合微服务架构的整体版本管理；以及与非Git的版本管理工具集成，扩大适用范围。

最终，一个好的变更日志自动生成Skill应该做到"润物细无声"——开发者只需写好每次提交，剩下的交给Skill自动完成。当发布版本时，一份完整、清晰、漂亮的CHANGELOG就静静地等在那里，等待与用户分享项目成长的每一个脚印。