SuperAPI AI Directory
Partner中文AI newsFavorites
Skillschangelog-generator

changelog-generator

Data & analytics

View repository

Updated 10-15 21:41

About this skill

changelog-generator - Intelligent Changelog Generator

Overview

When the user needs to generate or update a CHANGELOG, this skill automatically performs the following process:

  1. Analyze Git commit history
  2. Parse commits according to the Conventional Commits specification
  3. Intelligently categorize and organize changes
  4. Generate a CHANGELOG.md that conforms to the Keep a Changelog standard
  5. Support version releases and incremental updates

Supported Trigger Commands

Users can trigger this skill in the following ways:

  • "changelog" - Simple trigger word
  • "changelog" - Simple trigger word
  • "Help me generate a CHANGELOG" - Generate a complete CHANGELOG
  • "Update CHANGELOG" - Incrementally update the CHANGELOG
  • "Release a new version" - Release an official version
  • "Initialize changelog configuration" - Create a configuration file

Workflow

Step 1: Initialize Configuration (first use)

Command:

cd ~/.claude/skills/changelog-generator
npm install

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

Configuration File: .changelogrc.json

The interactive configuration will ask:

  • Current version number
  • Language selection (Chinese/English)
  • Whether to use emoji
  • Whether to display author information

Step 2: Generate CHANGELOG

Scenario A: Generate a complete CHANGELOG for the first time

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

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

Scenario B: Incrementally update the CHANGELOG

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

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

Scenario C: Release a new version

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

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

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

Step 3: Output File

Default output path: ./CHANGELOG.md

Example generated CHANGELOG:

# 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

...

Core Features

1. Intelligent Commit Parsing

Supports the Conventional Commits specification:

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

BREAKING CHANGE: Remove old auth API

Supported commit types:

  • feat: ✨ Features
  • fix: 🐛 Bug Fixes
  • docs: 📝 Documentation
  • style: 💄 Styles (can be hidden)
  • refactor: ♻️ Code Refactoring
  • perf: ⚡ Performance
  • test: ✅ Tests
  • build: 📦 Build System
  • ci: 👷 CI/CD
  • chore: 🔧 Chores (can be hidden)

2. Automatic Version Management

Automatically determine the version number based on the commit type:

Commit Type Version Impact Example
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 and Issue References

Automatically identify and link:

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

Generate links:

- **feat:** add new feature ([#123](https://github.com/user/repo/pull/123))

4. Breaking Change Detection

Two detection methods:

Method 1: Use BREAKING CHANGE footer

feat: add new API

BREAKING CHANGE: Old API is removed

Method 2: Use "!" (exclamation mark) marker

feat!: remove deprecated method

Configuration Options

Complete configuration example

{
  "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"]
  }
}

Use Cases

Scenario 1: First generation for a new project

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

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

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

Scenario 2: Daily development incremental updates

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

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

Scenario 3: Release a new version

# 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

Scenario 4: CI/CD automation

GitHub Actions:

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 Command Reference

init - Initialize configuration

changelog-generate init

Interactively create .changelogrc.json configuration file.

generate - Generate CHANGELOG

changelog-generate generate [options]

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

update - Incremental update

changelog-generate update [options]

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

release - Release version

changelog-generate release [options]

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

preview - Preview Unreleased

changelog-generate preview

Display the contents of the [Unreleased] section.

Best Practices

1. Standardized Commit Message

Use the Conventional Commits specification:

# 好的示例
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. Use Commitlint

Install commitlint to check commit messages:

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

Configure .commitlintrc.json:

{
  "extends": ["@commitlint/config-conventional"]
}

3. Git Hooks Automation

Use husky to check on commit:

npm install --save-dev husky

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

4. Regular Updates

It is recommended to update the CHANGELOG at the following times:

  • After each PR merge
  • Regular weekly updates
  • Must be updated before release

5. Version Release Process

# 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

Dependency Installation

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

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

Tech Stack

  • simple-git: Git Operations
  • conventional-commits-parser: Commit Parsing
  • semver: Version Management
  • handlebars: Template Engine
  • commander: CLI Framework
  • inquirer: Interactive Command Line
  • chalk: Terminal Colors
  • ora: Loading Animation

Troubleshooting

Issue 1: Git repository not found

Error: Not a git repository

Solution:

# 确保在 Git 仓库目录中
git status

# 或初始化 Git 仓库
git init

Issue 2: Unable to parse commits

Cause: Commit message does not conform to the Conventional Commits specification

Solution: Modify the configuration to categorize non-conforming commits under the "Other" type.

Issue 3: Generated CHANGELOG is empty

Check:

# 查看提交历史
git log --oneline

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

Extensions and Customization

Custom Templates

Create a custom template custom-template.hbs:

# 变更日志

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

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

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

Configure to use:

{
  "template": {
    "path": "./custom-template.hbs"
  }
}

Add new commit types

In .changelogrc.json add:

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

Integration with Other Tools

Integration with semantic-release

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

Integration with Renovate

.renovate.json:

{
  "automerge": true,
  "prCreation": "immediate",
  "commitMessagePrefix": "chore(deps):"
}

Version: 1.0.0 Author: Peter Fei License: MIT