---
name: changelog-generator
description: "智能变更日志生成器 - 自动分析Git提交历史，生成符合规范的CHANGELOG.md。支持语义化版本管理、多种输出格式、增量更新和GitHub/GitLab集成。"
license: MIT
---

# changelog-generator - 智能变更日志生成器

## 概述

当用户需要生成或更新 CHANGELOG 时，此 skill 会自动完成以下流程：
1. 分析 Git 提交历史
2. 根据 Conventional Commits 规范解析提交
3. 智能分类和组织变更
4. 生成符合 Keep a Changelog 标准的 CHANGELOG.md
5. 支持版本发布和增量更新

## 支持的触发指令

用户可以通过以下方式触发此 skill：
- "changelog" - 简易触发词
- "变更日志" - 简易触发词
- "帮我生成 CHANGELOG" - 生成完整的 CHANGELOG
- "更新 CHANGELOG" - 增量更新 CHANGELOG
- "发布新版本" - 发布正式版本
- "初始化 changelog 配置" - 创建配置文件

## 工作流程

### 步骤 1: 初始化配置（首次使用）

**命令**:
```bash
cd ~/.claude/skills/changelog-generator
npm install

# 在项目目录中初始化配置
cd /path/to/your/project
changelog-generate init
```

**配置文件**: `.changelogrc.json`

交互式配置会询问：
- 当前版本号
- 语言选择（中文/英文）
- 是否使用 emoji
- 是否显示作者信息

### 步骤 2: 生成 CHANGELOG

**场景 A: 首次生成完整 CHANGELOG**

```bash
# 生成所有历史提交的 CHANGELOG
changelog-generate generate --all

# 生成指定范围的 CHANGELOG
changelog-generate generate --from v1.0.0 --to v2.0.0
```

**场景 B: 增量更新 CHANGELOG**

```bash
# 更新 [Unreleased] 区域
changelog-generate update

# 从指定标签开始更新
changelog-generate update --from v2.0.0
```

**场景 C: 发布新版本**

```bash
# 自动确定版本号（交互式）
changelog-generate release

# 手动指定版本号
changelog-generate release --version 2.1.0

# 指定日期
changelog-generate release --version 2.1.0 --date 2023-11-10
```

### 步骤 3: 输出文件

**默认输出路径**: `./CHANGELOG.md`

**生成的 CHANGELOG 示例**:
```markdown
# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

## [2.0.0] - 2023-11-10

### 💥 BREAKING CHANGES

- **api:** Remove deprecated v1 endpoints (#123)

### ✨ Features

- **auth:** Add JWT authentication (#120)
- **api:** Add user profile endpoint (#121)

### 🐛 Bug Fixes

- **ui:** Fix button alignment issue (#122)

### 📝 Documentation

- Update API documentation

## [1.0.0] - 2023-10-01

...
```

## 核心功能

### 1. 智能提交解析

支持 Conventional Commits 规范：

```
feat(auth): add login functionality
^    ^      ^
type scope  subject

BREAKING CHANGE: Remove old auth API
```

**支持的提交类型**:
- `feat`: ✨ Features
- `fix`: 🐛 Bug Fixes
- `docs`: 📝 Documentation
- `style`: 💄 Styles (可隐藏)
- `refactor`: ♻️ Code Refactoring
- `perf`: ⚡ Performance
- `test`: ✅ Tests
- `build`: 📦 Build System
- `ci`: 👷 CI/CD
- `chore`: 🔧 Chores (可隐藏)

### 2. 自动版本管理

根据提交类型自动确定版本号：

| 提交类型 | 版本影响 | 示例 |
|---------|---------|------|
| BREAKING CHANGE | Major | 1.0.0 → 2.0.0 |
| feat | Minor | 1.0.0 → 1.1.0 |
| fix | Patch | 1.0.0 → 1.0.1 |

### 3. PR 和 Issue 引用

自动识别和链接：

```
feat: add new feature (#123)
fix: resolve bug (fixes #456)
```

生成链接：
```markdown
- **feat:** add new feature ([#123](https://github.com/user/repo/pull/123))
```

### 4. 破坏性变更检测

两种检测方式：

**方式 1**: 使用 `BREAKING CHANGE` footer
```
feat: add new API

BREAKING CHANGE: Old API is removed
```

**方式 2**: 使用 "!" (感叹号) 标记
```
feat!: remove deprecated method
```

## 配置选项

### 完整配置示例

```json
{
  "version": "1.0.0",
  "format": "keepachangelog",
  "language": "zh-CN",

  "display": {
    "emoji": true,
    "groupByType": true,
    "showAuthor": true,
    "showPR": true,
    "showIssue": true
  },

  "types": [
    { "type": "feat", "section": "Features", "emoji": "✨" },
    { "type": "fix", "section": "Bug Fixes", "emoji": "🐛" },
    { "type": "chore", "hidden": true }
  ],

  "exclude": {
    "types": ["style", "chore"],
    "scopes": ["deps"]
  }
}
```

## 使用场景

### 场景 1: 新项目首次生成

```bash
# 1. 初始化配置
changelog-generate init

# 2. 生成 CHANGELOG
changelog-generate generate --all

# 输出: CHANGELOG.md 包含所有历史提交
```

### 场景 2: 日常开发增量更新

```bash
# 在每次 PR 合并后或定期更新
git pull
changelog-generate update

# 查看 [Unreleased] 的内容
changelog-generate preview
```

### 场景 3: 发布新版本

```bash
# 1. 更新 CHANGELOG
changelog-generate update

# 2. 预览将要发布的内容
changelog-generate preview

# 3. 发布版本
changelog-generate release

# 4. 提交和推送
git add CHANGELOG.md
git commit -m "chore(release): 2.0.0"
git tag v2.0.0
git push && git push --tags
```

### 场景 4: CI/CD 自动化

**GitHub Actions**:
```yaml
name: Update Changelog

on:
  push:
    branches: [main]

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0

      - name: Update Changelog
        run: |
          npm install -g changelog-generate
          changelog-generate update

      - name: Commit
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add CHANGELOG.md
          git commit -m "docs: update changelog" || true
          git push
```

## CLI 命令参考

### `init` - 初始化配置

```bash
changelog-generate init
```

交互式创建 `.changelogrc.json` 配置文件。

### `generate` - 生成 CHANGELOG

```bash
changelog-generate generate [options]

Options:
  -f, --from <tag>    起始标签
  -t, --to <tag>      结束标签 (默认: HEAD)
  -o, --output <file> 输出文件 (默认: CHANGELOG.md)
  --all               包含所有历史提交
```

### `update` - 增量更新

```bash
changelog-generate update [options]

Options:
  -f, --from <tag>    起始标签（默认为最新标签）
  -o, --output <file> CHANGELOG 文件 (默认: CHANGELOG.md)
```

### `release` - 发布版本

```bash
changelog-generate release [options]

Options:
  -v, --version <version> 版本号
  -d, --date <date>       发布日期
  -o, --output <file>     CHANGELOG 文件
```

### `preview` - 预览 Unreleased

```bash
changelog-generate preview
```

显示 [Unreleased] 区域的内容。

## 最佳实践

### 1. 规范的 Commit Message

使用 Conventional Commits 规范：

```bash
# 好的示例
git commit -m "feat(auth): add OAuth2 support"
git commit -m "fix(ui): resolve button alignment issue"
git commit -m "docs: update installation guide"

# 避免的示例
git commit -m "update code"
git commit -m "fix bug"
git commit -m "wip"
```

### 2. 使用 Commitlint

安装 commitlint 检查提交消息：

```bash
npm install --save-dev @commitlint/cli @commitlint/config-conventional
```

配置 `.commitlintrc.json`:
```json
{
  "extends": ["@commitlint/config-conventional"]
}
```

### 3. Git Hooks 自动化

使用 husky 在提交时检查：

```bash
npm install --save-dev husky

# .husky/commit-msg
npx commitlint --edit $1
```

### 4. 定期更新

建议在以下时机更新 CHANGELOG：
- 每次 PR 合并后
- 每周定期更新
- 发布前必须更新

### 5. 版本发布流程

```bash
# 1. 确保所有变更已提交
git status

# 2. 更新 CHANGELOG
changelog-generate update

# 3. 预览内容
changelog-generate preview

# 4. 发布版本
changelog-generate release

# 5. 审查 CHANGELOG.md
git diff CHANGELOG.md

# 6. 提交和标签
git add CHANGELOG.md
git commit -m "chore(release): 2.0.0"
git tag v2.0.0

# 7. 推送
git push && git push --tags
```

## 依赖安装

```bash
# 使用 nvm 管理 Node.js 版本
nvm use 18

# 安装依赖
cd ~/.claude/skills/changelog-generator
npm install
```

## 技术栈

- **simple-git**: Git 操作
- **conventional-commits-parser**: 提交解析
- **semver**: 版本管理
- **handlebars**: 模板引擎
- **commander**: CLI 框架
- **inquirer**: 交互式命令行
- **chalk**: 终端颜色
- **ora**: 加载动画

## 故障排除

### 问题 1: 找不到 Git 仓库

**错误**: `Not a git repository`

**解决**:
```bash
# 确保在 Git 仓库目录中
git status

# 或初始化 Git 仓库
git init
```

### 问题 2: 无法解析提交

**原因**: 提交消息不符合 Conventional Commits 规范

**解决**: 修改配置，将不符合规范的提交归类到 "Other" 类型。

### 问题 3: 生成的 CHANGELOG 为空

**检查**:
```bash
# 查看提交历史
git log --oneline

# 检查配置中的排除规则
cat .changelogrc.json | grep exclude
```

## 扩展和自定义

### 自定义模板

创建自定义模板 `custom-template.hbs`:

```handlebars
# 变更日志

{{#each versions}}
## 版本 {{version}} ({{date}})

{{#each changes}}
**{{section}}**
{{#each commits}}
- {{subject}}
{{/each}}

{{/each}}
{{/each}}
```

配置使用：
```json
{
  "template": {
    "path": "./custom-template.hbs"
  }
}
```

### 添加新的提交类型

在 `.changelogrc.json` 中添加：

```json
{
  "types": [
    {
      "type": "security",
      "section": "Security",
      "emoji": "🔒",
      "priority": 2
    }
  ]
}
```

## 与其他工具集成

### 与 semantic-release 集成

```json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/git"
  ]
}
```

### 与 Renovate 集成

`.renovate.json`:
```json
{
  "automerge": true,
  "prCreation": "immediate",
  "commitMessagePrefix": "chore(deps):"
}
```

---

**版本**: 1.0.0
**作者**: Peter Fei
**许可**: MIT