一、概述：为什么需要自动化变更日志
在软件开发中，变更日志（Changelog）和Release Notes是团队协作与用户沟通的重要桥梁。手动维护这些文档不仅耗时且容易遗漏，而自动化工作流可以彻底解决这些问题。
自动化的核心价值：
- 一致性： 所有提交遵循统一规范，生成的变更日志格式统一
- 可追溯： 每次变更与具体提交一一对应，责任明确
- 高效率： 从提交代码到发布版本，全流程自动生成文档
- 低错误： 避免人工编写时的遗漏和格式错误
本工作流将 Claude Code 作为协处理引擎，结合业界成熟工具（commitlint、standard-version、semantic-release 等），构建端到端的自动化发布文档流水线。
代码提交
→
commitlint 验证
→
自动生成 Changelog
→
生成 Release Notes
→
GitHub Release
二、Conventional Commits 规范
Conventional Commits 是自动化变更日志的基础。它规定了提交信息的结构化格式，使工具能够自动解析提交内容并分类。
2.1 提交格式规范
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
2.2 提交类型（Type）详解
| 类型 |
标签 |
说明 |
是否出现在 Changelog |
| feat |
feat |
新功能（Feature） |
是 |
| fix |
fix |
Bug 修复 |
是 |
| docs |
docs |
文档变更 |
是 |
| refactor |
refactor |
代码重构 |
是 |
| perf |
perf |
性能优化 |
是 |
| test |
test |
测试相关 |
否 |
| chore |
chore |
构建/工具/依赖 |
否 |
| ci |
ci |
CI/CD 配置变更 |
否 |
2.3 BREAKING CHANGE 标记
当提交包含不兼容的 API 更改时，使用 BREAKING CHANGE 标记，这将触发主版本号升级。
feat(api): 重构用户认证接口
BREAKING CHANGE: 移除了旧的 JWT 认证方式，改用 OAuth 2.0。
所有客户端需要更新认证流程。
Closes #123
也可以在类型后添加 ! 来标记重大变更：
feat(api)!: 移除对 v1 接口的支持
2.4 Scoped 提交（Scope）
Scope 表示提交影响的范围/模块，使变更日志更加精细：
| 示例 |
说明 |
| feat(auth): 添加 OAuth 登录 |
影响 auth 模块 |
| fix(ui): 修复按钮对齐问题 |
影响 UI 组件 |
| docs(readme): 更新安装说明 |
影响 README 文档 |
| refactor(core): 重构数据层 |
影响 core 核心模块 |
2.5 最佳实践示例
feat(parser): 添加 Markdown 表格解析支持
实现 GFM 规范的标准表格解析，支持对齐语法。
Closes #89
fix(editor): 修复全屏模式下工具栏消失问题
在全屏切换时重新计算工具栏的 z-index 值，
确保其在 iframe 之上显示。
Fixes #234
perf(renderer): 优化虚拟列表渲染性能
使用 IntersectionObserver 替换滚动事件监听，
减少 60% 的无效渲染次数。
三、提交验证与规范化
要确保所有提交遵循 Conventional Commits 规范，需要在提交时进行自动化验证。
3.1 commitlint 配置
commitlint 是一个提交信息校验工具，配合 Husky 的 pre-commit 钩子使用。
npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [
2,
'always',
[
'feat', 'fix', 'docs', 'style',
'refactor', 'perf', 'test', 'chore',
'ci', 'build', 'revert'
]
],
'scope-case': [2, 'always', 'kebab-case'],
'subject-case': [2, 'never', ['start-case', 'pascal-case']],
'subject-empty': [2, 'never'],
'type-empty': [2, 'never'],
'header-max-length': [2, 'always', 100]
}
};
3.2 Husky 配置
npx husky init
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx --no -- commitlint --edit $1
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx lint-staged
3.3 自定义提交类型
对于特定项目，可以扩展提交类型规则：
rules: {
'type-enum': [2, 'always', [
'feat', 'fix', 'docs', 'style',
'refactor', 'perf', 'test', 'chore',
'ci', 'build', 'revert',
'i18n',
'a11y',
'api',
'deps',
'config'
]]
}
3.4 提交信息辅助工具
npm install --save-dev commitizen cz-conventional-changelog
{
"config": {
"commitizen": {
"path": "cz-conventional-changelog"
}
}
}
npx cz
通过交互式提示，开发者无需记忆提交格式，工具会引导填写类型、范围、描述等字段。
四、变更日志（Changelog）生成
变更日志是项目中最重要的可交付文档之一。业界遵循 Keep a Changelog 标准格式，结合 Conventional Commits 可以实现自动生成。
4.1 Keep a Changelog 标准格式
## [3.0.0] - 2026-04-15
### BREAKING
- 重构认证系统，移除 JWT 支持
### Added
- 添加 OAuth 2.0 登录支持
- 添加生物识别认证（指纹/面部）
- 添加会话管理仪表盘
### Fixed
- 修复 Token 刷新竞态条件
- 修复移动端登录页面布局问题
### Changed
- 优化密码哈希算法（bcrypt → argon2id）
- 升级 TypeScript 到 5.8 版本
4.2 standard-version 自动生成
standard-version 是最流行的变更日志自动生成工具之一，它基于 Conventional Commits 自动生成 changelog 并升级版本号。
npm install --save-dev standard-version
{
"scripts": {
"release": "standard-version",
"release:minor": "standard-version --release-as minor",
"release:patch": "standard-version --release-as patch",
"release:major": "standard-version --release-as major",
"release:dry": "standard-version --dry-run"
}
}
module.exports = {
types: [
{ type: 'feat', section: '🚀 新功能', hidden: false },
{ type: 'fix', section: '🐛 Bug 修复', hidden: false },
{ type: 'perf', section: '⚡ 性能优化', hidden: false },
{ type: 'docs', section: '📝 文档更新', hidden: false },
{ type: 'refactor', section: '♻️ 代码重构', hidden: false },
{ type: 'test', section: '✅ 测试', hidden: true },
{ type: 'chore', section: '🔧 杂项', hidden: true },
{ type: 'ci', section: '👷 CI/CD', hidden: true }
],
commitUrlFormat: 'https://github.com/user/repo/commits/{{hash}}',
compareUrlFormat: 'https://github.com/user/repo/compare/{{previousTag}}...{{currentTag}}',
issueUrlFormat: 'https://github.com/user/repo/issues/{{id}}'
};
4.3 release-it 配置
release-it 是一个更加全能的发布工具，集成了版本递增、changelog 生成、GitHub Release 创建等功能：
npm install --save-dev release-it @release-it/conventional-changelog
module.exports = {
git: {
commitMessage: 'chore: release v${version}',
tagName: 'v${version}',
tagAnnotation: 'Release v${version}'
},
npm: {
publish: true
},
github: {
release: true,
releaseName: 'v${version}',
comments: {
submit: true
}
},
plugins: {
'@release-it/conventional-changelog': {
preset: 'conventionalcommits',
infile: 'CHANGELOG.md',
header: '# Changelog\n\n自动生成的版本变更记录。\n'
}
}
};
4.4 auto-changelog 轻量方案
对于不需要版本管理的场景，auto-changelog 是一个轻量选择：
npm install --save-dev auto-changelog
{
"scripts": {
"changelog": "auto-changelog -p --sort-commits date --hide-credit"
}
}
auto-changelog --output CHANGELOG.md \
--template keepachangelog \
--unreleased \
--commit-limit false \
--handle-unknown resolve
4.5 基于 git log 的自动分类脚本
当不使用第三方工具时，可以直接通过 git log 结合 jq 实现简单的 changelog 生成：
#!/bin/bash
echo "# Changelog"
echo ""
echo "## [Unreleased]"
echo ""
for type in feat fix perf docs refactor; do
commits=$(git log "$1...HEAD" --grep="^${type}" \
--pretty=format:"- %s (%h)" \
--reverse)
if [ -n "$commits" ]; then
case $type in
feat) echo "### 🚀 新功能";;
fix) echo "### 🐛 Bug 修复";;
perf) echo "### ⚡ 性能优化";;
docs) echo "### 📝 文档更新";;
refactor) echo "### ♻️ 代码重构";;
esac
echo "$commits"
echo ""
fi
done
chmod +x generate-changelog.sh
./generate-changelog.sh v2.0.0
4.6 Unreleased 变更管理
Keep a Changelog 格式要求在发布前维护一个 [Unreleased] 区块，累积尚未发布的变更：
## [Unreleased]
### Added
- 用户导出 CSV 功能（#345）
### Fixed
- 修复搜索框输入延迟问题（#340）
---
## [2.1.0] - 2026-04-20
### Added
- 批量导入用户功能（#321）
通过以下脚本可以在发布时自动将 Unreleased 内容转换为版本区块：
const fs = require('fs');
const changelog = fs.readFileSync('CHANGELOG.md', 'utf8');
const newVersion = process.argv[2];
const today = new Date().toISOString().slice(0, 10);
const updated = changelog.replace(
'## [Unreleased]',
`## [${newVersion}] - ${today}`
);
fs.writeFileSync('CHANGELOG.md', updated);
console.log(`Promoted Unreleased to v${newVersion}`);
五、Release Notes 生成与定制
Release Notes 不同于 Changelog，它是面向最终用户的版本发布说明，需要更易读、更聚焦的呈现方式。
5.1 Release Notes 标准结构
## 版本概要
本次发布聚焦于性能优化和开发者体验改进，移除了多个
已弃用的 API，并引入了全新的插件系统。
## 新功能列表
- 插件系统：支持第三方扩展
- 暗色模式：跟随系统主题自动切换
- 小组件面板：可自定义仪表盘布局
## Bug 修复
- 修复大数据集下表格卡顿问题
- 修复导出 PDF 时中文字体缺失
- 修复 WebSocket 断线重连超时
## 重大变更
- BREAKING: 最低要求 Node.js 20+（#456）
- BREAKING: 移除 v1 REST API 端点
## 升级指南
1. 将 Node.js 升级到 20 LTS 或更高版本
2. 运行 `npm run migrate` 迁移配置文件
3. 将 API 调用从 `/api/v1/` 切换到 `/api/v2/`
## 兼容性说明
- 向后兼容 v2.x 的数据格式
- 不再支持 Internet Explorer 11
## 贡献者
感谢 @zhangsan、@lisi、@wangwu 的代码贡献
5.2 基于模板的 Release Notes 生成
# Release Notes {{version}}
## 版本概要
{{summary}}
## 更新详情
{{#each sections}}
### {{title}}
{{#each items}}
- {{this}}
{{/each}}
{{/each}}
## 升级指南
{{migrationGuide}}
## 兼容性说明
{{compatibility}}
---
> 发布日期：{{date}}
> 发布负责人：{{author}}
const { execSync } = require('child_process');
const fs = require('fs');
function getCommitsByType(fromTag, toTag) {
const types = ['feat', 'fix', 'perf', 'docs', 'refactor'];
const result = {};
types.forEach(type => {
const cmd = `git log ${fromTag}...${toTag} ` +
`--grep="^${type}" --pretty=format:"%s||%h||%an" --reverse`;
try {
const output = execSync(cmd).toString().trim();
result[type] = output ? output.split('\n').map(line => {
const [subject, hash, author] = line.split('||');
return { subject, hash, author };
}) : [];
} catch {
result[type] = [];
}
});
return result;
}
function generateReleaseNotes(version, prevTag) {
const commits = getCommitsByType(prevTag, `v${version}`);
const sections = {
feat: { title: '新功能', icon: '🚀', items: [] },
fix: { title: 'Bug 修复', icon: '🐛', items: [] },
perf: { title: '性能优化', icon: '⚡', items: [] },
docs: { title: '文档更新', icon: '📝', items: [] }
};
let notes = `# Release Notes v${version}\n\n`;
notes += `> 发布日期：${new Date().toISOString().slice(0, 10)}\n\n`;
Object.entries(commits).forEach(([type, commitList]) => {
if (commitList.length > 0 && sections[type]) {
notes += `## ${sections[type].icon} ${sections[type].title}\n\n`;
commitList.forEach(c => {
const scope = c.subject.match(/\(([^)]+)\)/);
const desc = c.subject.replace(/^(feat|fix|perf|docs)(\([^)]+\))?:\s*/, '');
notes += `- ${desc} (@${c.author}, [${c.hash}](https://...))\n`;
});
notes += '\n';
}
});
notes += `---\n\n贡献者：${
[...new Set(Object.values(commits)
.flat().map(c => c.author))]
.join('、')
}\n`;
return notes;
}
console.log(generateReleaseNotes('3.0.0', 'v2.5.0'));
5.3 贡献者致谢自动生成
git log v2.0.0...v3.0.0 --format="%aN" \
| sort -u \
| awk '{print "- @" $0}'
const { execSync } = require('child_process');
function getContributors(fromTag, toTag) {
const raw = execSync(
`git shortlog -sne ${fromTag}...${toTag}`,
{ encoding: 'utf8' }
);
return raw.trim().split('\n').map(line => {
const match = line.match(/^\s*(\d+)\s+(.+?)\s+<(.+)>$/);
if (!match) return null;
return {
commits: parseInt(match[1]),
name: match[2],
email: match[3]
};
}).filter(Boolean).sort((a, b) => b.commits - a.commits);
}
const contributors = getContributors('v2.0.0', 'v3.0.0');
console.log('贡献者列表（按提交数排序）：');
contributors.forEach(c => {
console.log(` ${c.name.padEnd(20)} ${c.commits} commits`);
});
六、版本发布自动化
完整的发布自动化包括版本递增、标签创建、GitHub Release 发布以及多渠道通知。
6.1 semantic-release 完整流程
semantic-release 是目前最完善的自动化发布工具，全自动完成版本分析、changelog 生成、发布和通知：
npm install --save-dev semantic-release \
@semantic-release/commit-analyzer \
@semantic-release/release-notes-generator \
@semantic-release/changelog \
@semantic-release/github \
@semantic-release/git \
@semantic-release/npm
module.exports = {
branches: ['main', 'next'],
plugins: [
['@semantic-release/commit-analyzer', {
preset: 'conventionalcommits',
releaseRules: [
{ type: 'refactor', release: 'patch' },
{ type: 'style', release: 'patch' },
{ type: 'perf', release: 'patch' },
{ type: 'docs', release: 'patch' },
{ breaking: true, release: 'major' }
]
}],
['@semantic-release/release-notes-generator', {
preset: 'conventionalcommits',
writerOpts: {
groupBy: 'type',
commitGroupsSort: ['feat', 'fix', 'perf', 'docs', 'refactor'],
commitsSort: ['scope', 'subject']
}
}],
['@semantic-release/changelog', {
changelogFile: 'CHANGELOG.md',
changelogTitle: '# Changelog\n\n自动生成的版本变更记录。\n'
}],
['@semantic-release/git', {
assets: ['CHANGELOG.md', 'package.json'],
message: 'chore(release): ${nextRelease.version}\n\n${nextRelease.notes}'
}],
['@semantic-release/github', {
assets: [
{ path: 'dist/*.zip', label: '发布包' },
{ path: 'CHANGELOG.md', label: '变更日志' }
],
discussionCategoryName: '发布公告'
}]
]
};
6.2 自动版本递增规则
| 提交类型 |
版本递增 |
示例 |
| BREAKING CHANGE |
Major（主版本） |
2.1.0 → 3.0.0 |
| feat |
Minor（次版本） |
2.1.0 → 2.2.0 |
| fix |
Patch（修订号） |
2.1.0 → 2.1.1 |
| perf |
Patch（修订号） |
2.1.0 → 2.1.1 |
| docs/refactor |
Patch（修订号） |
2.1.0 → 2.1.1 |
| chore/test/ci |
不发布 |
- |
6.3 标签创建与 GitHub Release
VERSION="3.0.0"
TAG="v$VERSION"
npm version $VERSION --no-git-tag-version
npx standard-version --skip.bump --skip.commit
git add package.json CHANGELOG.md
git commit -m "chore(release): v$VERSION"
git tag -a "$TAG" -m "Release $TAG"
git push origin main --tags
gh release create "$TAG" \
--title "v$VERSION" \
--notes-file <(npx standard-version --dry-run 2>&1 | tail -n +5) \
--discussion-category "发布公告"
6.4 多渠道发布通知
发布完成后，自动通知各个渠道的团队成员和用户：
const https = require('https');
async function notifyRelease(version, notes) {
const message = formatMessage(version, notes);
await sendTelegram(process.env.TELEGRAM_BOT_TOKEN,
process.env.TELEGRAM_CHAT_ID, message);
await sendSlack(process.env.SLACK_WEBHOOK_URL, {
text: message,
blocks: buildSlackBlocks(version, notes)
});
await sendEmail(
process.env.SMTP_HOST,
process.env.NOTIFICATION_EMAILS.split(','),
`[Release] v${version}`,
message
);
}
function formatMessage(version, notes) {
return `🎉 v${version} 已发布！\n\n` +
`${notes.slice(0, 500)}...\n\n` +
`查看详情：https://github.com/user/repo/releases/tag/v${version}`;
}
function buildSlackBlocks(version, notes) {
return [
{
type: 'header',
text: { type: 'plain_text', text: `🎉 v${version} 已发布` }
},
{
type: 'section',
text: { type: 'mrkdwn', text: notes.slice(0, 300) }
},
{
type: 'actions',
elements: [{
type: 'button',
text: { type: 'plain_text', text: '查看 Release' },
url: `https://github.com/user/repo/releases/tag/v${version}`
}]
}
];
}
curl -X POST -H 'Content-type: application/json' \
--data '{
"text": "🚀 新版本 v3.0.0 已发布！\n查看详情：https://github.com/user/repo/releases/tag/v3.0.0"
}' \
https://hooks.slack.com/services/xxx/yyy/zzz
name: Release Notification
on:
release:
types: [published]
jobs:
notify:
runs-on: ubuntu-latest
steps:
- name: Notify Telegram
uses: appleboy/telegram-action@master
with:
to: ${{ secrets.TELEGRAM_CHAT_ID }}
token: ${{ secrets.TELEGRAM_BOT_TOKEN }}
message: |
🎉 新版本 ${{ github.event.release.tag_name }} 已发布！
${{ github.event.release.body }}
下载地址：${{ github.event.release.html_url }}
- name: Notify Slack
uses: 8398a7/action-slack@v3
with:
status: custom
fields: repo,message
custom_payload: |
{
"text": "🎉 新版本 ${{ github.event.release.tag_name }} 已发布！",
"attachments": [{
"title": "查看 Release",
"title_link": "${{ github.event.release.html_url }}",
"text": "变更内容请查看 Release 页面。"
}]
}
webhook_url: ${{ secrets.SLACK_WEBHOOK_URL }}
- name: Notify Email
uses: dawidd6/action-send-mail@v3
with:
server_address: smtp.example.com
server_port: 465
username: ${{ secrets.MAIL_USERNAME }}
password: ${{ secrets.MAIL_PASSWORD }}
subject: 新版本 ${{ github.event.release.tag_name }} 发布通知
to: ${{ secrets.NOTIFICATION_EMAILS }}
body: |
版本：${{ github.event.release.tag_name }}
发布说明：${{ github.event.release.html_url }}
变更日志：https://github.com/user/repo/blob/main/CHANGELOG.md
6.5 制品与变更日志关联
name: Build and Release
on:
release:
types: [created]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 构建项目
run: npm run build
- name: 打包制品
run: |
mkdir -p release-artifacts
cp -r dist/* release-artifacts/
cp CHANGELOG.md release-artifacts/
cd release-artifacts
zip -r "../release-${{ github.event.release.tag_name }}.zip" .
- name: 上传 Release 制品
uses: actions/upload-release-asset@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
upload_url: ${{ github.event.release.upload_url }}
asset_path: ./release-${{ github.event.release.tag_name }}.zip
asset_name: release-${{ github.event.release.tag_name }}.zip
asset_content_type: application/zip
七、CI/CD 集成
将变更日志和发布流程集成到 CI/CD 流水线中，实现全自动化。
7.1 提交时验证（GitHub Actions）
name: Commit Lint
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
commitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: 设置 Node.js
uses: actions/setup-node@v4
with:
node-version: 20
- name: 安装依赖
run: npm ci
- name: 验证 PR 提交信息
uses: wagoid/commitlint-github-action@v5
with:
configFile: commitlint.config.js
helpURL: https://conventionalcommits.org
- name: 验证 PR 标题
run: |
echo "${{ github.event.pull_request.title }}" \
| npx commitlint
7.2 PR 时验证
name: PR Checks
on:
pull_request:
types: [opened, edited, labeled, unlabeled]
jobs:
check-pr-title:
runs-on: ubuntu-latest
steps:
- name: 验证 PR 标题格式
uses: action-validator/pr-title@v1
with:
pattern: '^(feat|fix|docs|refactor|perf|test|chore|ci)(\(.+\))?!?: .+$'
changelog-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: 检查 Changelog 是否更新
run: |
if git diff --name-only origin/main...HEAD | grep -q CHANGELOG.md; then
echo "✓ Changelog 已更新"
else
echo "⚠️ 请考虑是否需要在 CHANGELOG.md 中添加变更记录"
fi
7.3 发布时自动生成完整流水线
name: Automated Release
on:
push:
branches: [main]
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
issues: write
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
persist-credentials: false
- name: 设置 Node.js
uses: actions/setup-node@v4
with:
node-version: 20
- name: 安装依赖
run: npm ci
- name: 运行测试
run: npm test
- name: 构建项目
run: npm run build
- name: Semantic Release
uses: cycjimmy/semantic-release-action@v4
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
with:
semantic_version: 24
extra_plugins: |
@semantic-release/changelog
@semantic-release/git
conventional-changelog-conventionalcommits
7.4 制品与变更日志关联
在每个发布版本中，将变更日志与构建制品打包在一起，确保用户下载的制品包含完整的变更说明：
#!/bin/bash
VERSION=$(node -p "require('./package.json').version")
echo "生成 v${VERSION} 变更摘要..."
cat > dist/RELEASE_NOTES.txt << EOF
================================
项目名称 v${VERSION}
发布日期：$(date +%Y-%m-%d)
================================
$(npx conventional-changelog -p conventionalcommits -r 2)
---
完整变更日志：CHANGELOG.md
EOF
echo "变更日志已嵌入到构建制品中"
echo "文件：dist/RELEASE_NOTES.txt"
CI/CD 集成最佳实践：
- 提交时： commitlint 验证格式，Husky 拦截不合规提交
- PR 时： 检查 PR 标题是否符合规范，标记 changelog 是否需要更新
- 合并到主干： semantic-release 自动分析提交，决定是否发布新版本
- 发布时： 生成 Release Notes，创建 GitHub Release，发送多渠道通知
- 事后： 制品存档，变更日志永久保留在发行版中
八、CLAUDE.md 配置
在 CLAUDE.md 文件中配置提交规范和 changelog 生成规则，让 Claude Code 在开发过程中自动遵循规范。
8.1 提交规范配置
所有 Git 提交必须遵循 Conventional Commits 规范：
```
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
```
- feat: 新功能（对应 Minor 版本递增）
- fix: Bug 修复（对应 Patch 版本递增）
- docs: 文档变更（对应 Patch 版本递增）
- refactor: 代码重构（对应 Patch 版本递增）
- perf: 性能优化（对应 Patch 版本递增）
- test: 测试相关（不触发发布）
- chore: 杂项/工具（不触发发布）
- ci: CI/CD 变更（不触发发布）
- BREAKING CHANGE: 在 footer 中添加，或类型后加 ! 号
触发 Major 版本递增
feat(auth): 添加 OAuth 2.0 登录支持
fix(ui): 修复按钮在 Safari 中的样式问题
refactor(core)!: 重构数据访问层，移除 deprecated API
8.2 Changelog 生成规则配置
变更日志遵循 Keep a Changelog 格式：
```
# Changelog
## [Unreleased]
## [主版本号.次版本号.修订号] - 发布日期
### Added - 新功能（对应 feat 提交）
### Fixed - Bug 修复（对应 fix 提交）
### Changed - 变更/重构（对应 refactor/perf 提交）
### Deprecated - 即将弃用的功能
### Removed - 已移除的功能
### Security - 安全修复
```
```bash
npx standard-version --dry-run
npx standard-version --release-as minor
npx standard-version && git push --follow-tags origin main
```
8.3 Release Notes 模板配置
发布新版本时，生成如下格式的 Release Notes：
```markdown
# Release Notes v{version}
## 版本概要
{由 Claude Code 根据提交总结本次发布的核心价值}
## 新功能
{feat 类型的提交列表，每个条目包含说明和提交者}
## Bug 修复
{fix 类型的提交列表}
## 性能优化
{perf 类型的提交列表}
## 重大变更（如果有）
{BREAKING CHANGE 内容}
## 升级指南
{需要用户执行的操作步骤}
## 贡献者
{按提交数排序的贡献者列表}
```
8.4 完整 CLAUDE.md 配置示例
本项目使用 Conventional Commits 规范管理提交信息，
通过 semantic-release 实现全自动版本发布。
所有提交必须遵循格式：
```
():
```
允许类型：feat | fix | docs | refactor | perf | test | chore | ci
重大变更在描述末尾添加 BREAKING CHANGE 标记。
1. 合并到 main 分支后自动触发 semantic-release
2. semantic-release 分析提交记录，自动确定版本递增
3. 自动生成 CHANGELOG.md 并提交
4. 创建 Git Tag 和 GitHub Release
5. 发送发布通知到 Slack 和 Telegram
```bash
npx semantic-release --dry-run
npx semantic-release --no-ci
```
- CHANGELOG.md - 完整的变更历史
- Release Notes 自动在 GitHub Release 页面生成
提示：将配置与实际工具结合
CLAUDE.md 中的配置应当与实际安装的工具（commitlint、Husky、semantic-release 等）保持一致。当 Claude Code 读取 CLAUDE.md 后，会自动遵循其中的提交规范和发布流程，确保人工操作和自动化流程的一致性。
九、核心要点总结
自动化变更日志与Release Notes工作流要点
- Conventional Commits 是基石： 所有自动化都依赖于规范的提交信息结构，类型、范围、描述和 BREAKING CHANGE 标记缺一不可
- commitlint + Husky 保证规范落地： 在提交时强制验证格式，从源头确保数据质量
- Changelog 生成工具体系成熟： standard-version 适合简单场景，semantic-release 适合全自动化流程，auto-changelog 适合轻量需求
- Release Notes 面向用户： 区别于 Changelog，需要包含版本概要、新功能、Bug 修复、重大变更、升级指南、贡献者致谢等面向最终用户的内容
- 版本发布自动化： 自动版本递增、标签创建、GitHub Release 创建、多渠道通知（Telegram、Slack、邮件）构成完整发布流水线
- CI/CD 全流程集成： 提交时验证格式、PR 时检查规范、合并时自动分析提交并触发发布、发布时生成文档和通知
- CLAUDE.md 统一规范： 将提交规范、changelog 生成规则、Release Notes 模板写在 CLAUDE.md 中，让 Claude Code 在开发过程中自动遵循
提交代码 → commitlint 验证格式
↓
合并到 main 分支
↓
semantic-release 自动分析
↓
版本递增 + CHANGELOG.md 更新 + Git Tag
↓
GitHub Release 创建 + 多渠道通知
推荐技术栈
| 用途 |
推荐工具 |
备选方案 |
| 提交规范 |
commitizen + cz-conventional-changelog |
git-cz / 手动遵循规范 |
| 提交验证 |
commitlint + Husky |
simple-git-hooks |
| Changelog 生成 |
standard-version |
auto-changelog / git-cliff |
| 全自动发布 |
semantic-release |
release-it / changesets |
| 发布通知 |
GitHub Actions 自定义工作流 |
Webhook + Zapier / n8n |
| 配置管理 |
CLAUDE.md |
.github/CONTRIBUTING.md |
通过这套工作流，团队可以彻底告别手动编写发布文档的繁琐工作，专注于核心业务开发。每次代码提交都为自动化流程提供数据，每次发布都自动生成结构化的变更日志和 Release Notes，真正实现"提交即文档"的现代化开发体验。