Back to Details

changelog-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Changelog & Release Notes Writer

变更日志与发布说明生成工具

Generate professional changelogs and release notes from version control history.
从版本控制历史生成专业的变更日志和发布说明。

Core Workflow

核心工作流程

  1. Analyze commits: Parse git history since last release
  2. Categorize changes: Group by type (feat, fix, docs, etc.)
  3. Identify breaking changes: Flag incompatible changes
  4. Extract highlights: Surface most important changes
  5. Format document: Follow Keep a Changelog format
  6. Suggest version: Recommend semantic version bump
  7. Generate release notes: Create user-friendly summary
  1. 分析提交记录：解析上次发布以来的Git历史
  2. 分类变更内容：按类型（feat、fix、docs等）分组
  3. 识别重大变更：标记不兼容的变更
  4. 提取重点内容：突出最重要的变更
  5. 格式化文档：遵循Keep a Changelog格式
  6. 建议版本号：推荐语义化版本升级
  7. 生成发布说明：创建用户友好的摘要

Commit Analysis

提交记录分析

Extract Information From

提取信息来源

  • Commit messages (preferably conventional commits)
  • PR titles and descriptions
  • Issue references (#123)
  • Merge commit messages
  • Commit authors
  • 提交信息（优先采用约定式提交格式）
  • PR标题和描述
  • 问题引用（#123）
  • 合并提交信息
  • 提交作者

Parse Patterns

解析规则

feat(auth): add OAuth2 support
^    ^      ^
|    |      └─ Description
|    └─ Scope (optional)
└─ Type
Types to Categories:
  • feat
    → Added
  • fix
    → Fixed
  • docs
    → Documentation
  • style
    , 
    refactor
    → Changed
  • perf
    → Performance
  • test
    → Testing
  • chore
    , 
    ci
    → Internal
  • BREAKING CHANGE
    → Breaking Changes
feat(auth): add OAuth2 support
^    ^      ^
|    |      └─ 描述
|    └─ 范围（可选）
└─ 类型
类型与分类对应：
  • feat
    → 新增功能
  • fix
    → 问题修复
  • docs
    → 文档更新
  • style
    、
    refactor
    → 代码变更
  • perf
    → 性能优化
  • test
    → 测试相关
  • chore
    、
    ci
    → 内部维护
  • BREAKING CHANGE
    → 重大变更

Changelog Format (Keep a Changelog)

变更日志格式（遵循Keep a Changelog）

markdown
undefined
markdown
undefined

Changelog

Changelog

All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[Unreleased]

Added

Added

  • New feature X
  • Support for Y
  • New feature X
  • Support for Y

Changed

Changed

  • Updated Z behavior
  • Updated Z behavior

Fixed

Fixed

  • Resolved issue #123
  • Resolved issue #123

[2.1.0] - 2024-01-15

[2.1.0] - 2024-01-15

Added

Added

  • OAuth2 authentication support
  • User profile management API
  • Dark mode toggle
  • OAuth2 authentication support
  • User profile management API
  • Dark mode toggle

Changed

Changed

  • Improved error messages
  • Updated dependencies to latest versions
  • Improved error messages
  • Updated dependencies to latest versions

Deprecated

Deprecated

  • Legacy authentication method (will be removed in 3.0.0)
  • Legacy authentication method (will be removed in 3.0.0)

Fixed

Fixed

  • Memory leak in WebSocket connection
  • Incorrect date formatting in reports
  • Race condition in concurrent requests
  • Memory leak in WebSocket connection
  • Incorrect date formatting in reports
  • Race condition in concurrent requests

Security

Security

  • Patched XSS vulnerability in user input
  • Patched XSS vulnerability in user input

[2.0.0] - 2023-12-01

[2.0.0] - 2023-12-01

Breaking Changes

Breaking Changes

  • ⚠️ Removed support for Node.js 16
  • ⚠️ Changed API response format for 
    /users
    endpoint
  • ⚠️ Renamed 
    config.yaml
    to 
    config.yml
  • ⚠️ Removed support for Node.js 16
  • ⚠️ Changed API response format for 
    /users
    endpoint
  • ⚠️ Renamed 
    config.yaml
    to 
    config.yml

Added

Added

  • Complete API rewrite with improved performance
  • WebSocket support for real-time updates
  • Complete API rewrite with improved performance
  • WebSocket support for real-time updates

Migration Guide

Migration Guide

See MIGRATION_v2.md for upgrade instructions.
undefined
See MIGRATION_v2.md for upgrade instructions.
undefined

Release Notes Format

发布说明格式

markdown
undefined
markdown
undefined

Release v2.1.0 - "Feature Release Name"

Release v2.1.0 - "Feature Release Name"

Released: January 15, 2024
Released: January 15, 2024

🎉 Highlights

🎉 重点更新

This release brings major improvements to authentication and user experience:
  • OAuth2 Support: Users can now sign in with Google, GitHub, and Microsoft
  • Dark Mode: Toggle between light and dark themes
  • Performance: 40% faster API response times
本次发布在认证和用户体验方面带来了重大改进：
  • OAuth2 支持：用户现在可以通过Google、GitHub和Microsoft登录
  • 深色模式：在浅色和深色主题之间切换
  • 性能提升：API响应速度提升40%

✨ New Features

✨ 新功能

  • OAuth2 authentication with popular providers (#456)
  • User profile management API (#478)
  • Dark mode toggle in settings (#492)
  • Export data in CSV format (#501)
  • 支持主流服务商的OAuth2认证（#456）
  • 用户资料管理API（#478）
  • 设置中的深色模式切换（#492）
  • CSV格式数据导出（#501）

🐛 Bug Fixes

🐛 问题修复

  • Fixed memory leak in WebSocket connections (#489)
  • Resolved incorrect date formatting in reports (#495)
  • Fixed race condition in concurrent API requests (#503)
  • 修复WebSocket连接中的内存泄漏问题（#489）
  • 解决报告中日期格式错误的问题（#495）
  • 修复并发API请求中的竞态条件问题（#503）

🔄 Changes

🔄 功能变更

  • Improved error messages across the application
  • Updated all dependencies to latest stable versions
  • Refined UI animations for smoother experience
  • 优化了全应用的错误提示信息
  • 将所有依赖更新至最新稳定版本
  • 优化UI动画，提升流畅度

🔒 Security

🔒 安全更新

  • Patched XSS vulnerability in user input validation
  • Updated JWT library to address CVE-2024-1234
  • 修复用户输入验证中的XSS漏洞
  • 更新JWT库以修复CVE-2024-1234漏洞

📚 Documentation

📚 文档更新

  • Added OAuth2 setup guide
  • Updated API reference with new endpoints
  • Improved troubleshooting section
  • 添加OAuth2设置指南
  • 更新API文档，新增端点说明
  • 优化故障排查章节

🙏 Contributors

🙏 贡献者

Thank you to all contributors who made this release possible:
  • @alice - OAuth2 implementation
  • @bob - Dark mode feature
  • @charlie - Bug fixes and testing
感谢所有为本次发布做出贡献的开发者：
  • @alice - OAuth2功能实现
  • @bob - 深色模式功能开发
  • @charlie - 问题修复与测试

📦 Installation

📦 安装方式

bash
npm install project-name@2.1.0
bash
npm install project-name@2.1.0

or

or

yarn add project-name@2.1.0
undefined
yarn add project-name@2.1.0
undefined

🔗 Links

🔗 相关链接

Note: This is a minor release. No breaking changes. Safe to upgrade from 2.0.x.
undefined
注意： 这是一个小版本更新，无重大变更，可从2.0.x版本安全升级。
undefined

Semantic Versioning Rules

语义化版本规则

Given a version number MAJOR.MINOR.PATCH (e.g., 2.1.0):
  1. MAJOR (2.x.x → 3.x.x)
    • Breaking changes
    • Incompatible API changes
    • Removed features
  2. MINOR (2.1.x → 2.2.x)
    • New features
    • Backward-compatible functionality
    • Deprecated features
  3. PATCH (2.1.0 → 2.1.1)
    • Bug fixes
    • Security patches
    • Performance improvements
Special versions:
  • 0.x.x
    - Initial development (breaking changes allowed in minor)
  • x.y.0-alpha.1
    - Pre-release
  • x.y.0-beta.2
    - Beta release
  • x.y.0-rc.1
    - Release candidate
版本号格式为 MAJOR.MINOR.PATCH（例如：2.1.0）：
  1. MAJOR（2.x.x → 3.x.x）
    • 重大变更
    • 不兼容的API变更
    • 移除功能
  2. MINOR（2.1.x → 2.2.x）
    • 新增功能
    • 向后兼容的功能改进
    • 标记为弃用的功能
  3. PATCH（2.1.0 → 2.1.1）
    • 问题修复
    • 安全补丁
    • 性能优化
特殊版本：
  • 0.x.x
    - 初始开发阶段（小版本允许重大变更）
  • x.y.0-alpha.1
    - 预发布版本
  • x.y.0-beta.2
    - Beta版本
  • x.y.0-rc.1
    - 候选发布版本

Git Commands for Changelog Generation

用于生成变更日志的Git命令

bash
undefined
bash
undefined

Get commits since last tag

获取上次标签以来的提交记录

git log $(git describe --tags --abbrev=0)..HEAD --oneline
git log $(git describe --tags --abbrev=0)..HEAD --oneline

Get commits between two tags

获取两个标签之间的提交记录

git log v2.0.0..v2.1.0 --oneline
git log v2.0.0..v2.1.0 --oneline

Get commits with PR numbers

获取包含PR编号的提交记录

git log --merges --pretty=format:"%s" v2.0.0..HEAD
git log --merges --pretty=format:"%s" v2.0.0..HEAD

Get contributors

获取贡献者列表

git log v2.0.0..HEAD --format='%aN' | sort -u
git log v2.0.0..HEAD --format='%aN' | sort -u

Get commit count by type

按类型统计提交数量

git log v2.0.0..HEAD --oneline | grep -E '^[a-f0-9]+ (feat|fix|docs)' | cut -d' ' -f2 | sort | uniq -c
undefined
git log v2.0.0..HEAD --oneline | grep -E '^[a-f0-9]+ (feat|fix|docs)' | cut -d' ' -f2 | sort | uniq -c
undefined

Breaking Changes Detection

重大变更检测

Look for these indicators:
  • Commit message contains 
    BREAKING CHANGE:
  • Commit type has 
    !
    (e.g., 
    feat!:
    )
  • PR labeled with "breaking-change"
  • Major dependency updates
  • API endpoint changes
  • Config file format changes
Document clearly:
markdown
undefined
关注以下指标：
  • 提交信息包含 
    BREAKING CHANGE:
  • 提交类型带有 
    !
    （例如：
    feat!:
    ）
  • PR标记有“breaking-change”标签
  • 主要依赖版本更新
  • API端点变更
  • 配置文件格式变更
清晰记录：
markdown
undefined

Breaking Changes

重大变更

⚠️ API Response Format Changed
The 
/api/users
endpoint now returns:
json
// Before
{ "data": [...] }

// After
{ "users": [...], "total": 100 }

**Migration:** Update your API client to access `users` instead of `data`.
⚠️ API响应格式变更
/api/users
端点现在返回：
json
// 变更前
{ "data": [...] }

// 变更后
{ "users": [...], "total": 100 }

**迁移说明：** 更新你的API客户端，从`users`字段获取数据，而非`data`字段。

Automation Tools

自动化工具

Using conventional-changelog

使用conventional-changelog

bash
npm install -g conventional-changelog-cli
bash
npm install -g conventional-changelog-cli

Generate changelog

生成变更日志

conventional-changelog -p angular -i CHANGELOG.md -s
conventional-changelog -p angular -i CHANGELOG.md -s

Generate for specific version

为特定版本生成变更日志

conventional-changelog -p angular -i CHANGELOG.md -s -r 0
undefined
conventional-changelog -p angular -i CHANGELOG.md -s -r 0
undefined

Using git-cliff

使用git-cliff

bash
undefined
bash
undefined

Install git-cliff

安装git-cliff

cargo install git-cliff
cargo install git-cliff

Generate changelog

生成变更日志

git-cliff --tag v2.1.0 > CHANGELOG.md
git-cliff --tag v2.1.0 > CHANGELOG.md

Generate release notes

生成发布说明

git-cliff --tag v2.1.0 --unreleased
undefined
git-cliff --tag v2.1.0 --unreleased
undefined

GitHub Release Script

GitHub发布脚本

bash
#!/bin/bash
bash
#!/bin/bash

scripts/release.sh

scripts/release.sh

VERSION=$1 PREVIOUS_TAG=$(git describe --tags --abbrev=0)
VERSION=$1 PREVIOUS_TAG=$(git describe --tags --abbrev=0)

Generate release notes

生成发布说明

gh release create "$VERSION"
--title "Release $VERSION"
--notes "$(git log $PREVIOUS_TAG..HEAD --pretty=format:'- %s')"
undefined
gh release create "$VERSION"
--title "Release $VERSION"
--notes "$(git log $PREVIOUS_TAG..HEAD --pretty=format:'- %s')"
undefined

User-Facing vs Developer-Facing

用户视角 vs 开发者视角

User-Facing (Release Notes)

用户视角（发布说明）

  • Focus on benefits and features
  • Less technical jargon
  • Include screenshots/demos
  • Highlight user experience improvements
  • Provide upgrade instructions
  • 聚焦功能收益
  • 减少技术术语
  • 包含截图/演示
  • 突出用户体验改进
  • 提供升级指南

Developer-Facing (Changelog)

开发者视角（变更日志）

  • Technical details
  • API changes
  • Breaking changes with migration guides
  • Dependencies updates
  • Internal refactorings
  • 技术细节
  • API变更
  • 带有迁移指南的重大变更
  • 依赖更新
  • 内部重构

Templates by Project Type

按项目类型分类的模板

Library/Package

类库/包

Focus on: API changes, breaking changes, new methods
重点：API变更、重大变更、新增方法

Application

应用程序

Focus on: New features, bug fixes, UI improvements
重点：新功能、问题修复、UI改进

CLI Tool

CLI工具

Focus on: New commands, flag changes, behavior changes
重点：新命令、参数变更、行为变更

API Service

API服务

Focus on: Endpoint changes, performance, security
重点：端点变更、性能、安全

Best Practices

最佳实践

  1. Be specific: "Fixed login bug" → "Fixed session timeout on mobile"
  2. Link issues: Reference GitHub issues (#123)
  3. Credit contributors: Acknowledge work
  4. Highlight impact: Mark breaking changes clearly
  5. Group logically: By type, not chronologically
  6. Update regularly: With each release
  7. Follow conventions: Keep a Changelog format
  8. Semantic versioning: Use correctly
  1. 具体明确：“修复登录问题” → “修复移动端会话超时问题”
  2. 关联问题：引用GitHub问题编号（#123）
  3. 感谢贡献者：认可开发者的工作
  4. 突出影响：清晰标记重大变更
  5. 逻辑分组：按类型分组，而非按时间顺序
  6. 定期更新：每次发布都更新
  7. 遵循规范：采用Keep a Changelog格式
  8. 语义化版本：正确使用版本规则

Changelog Entry Examples

变更日志条目示例

Good Examples

优秀示例

markdown
undefined
markdown
undefined

Added

Added

  • OAuth2 authentication support (#456) - @alice
  • Export data in CSV format with custom column selection (#501)
  • OAuth2 authentication support (#456) - @alice
  • Export data in CSV format with custom column selection (#501)

Fixed

Fixed

  • Resolved memory leak in WebSocket connections affecting long-running sessions (#489)
  • Fixed race condition in concurrent API requests that caused data inconsistency (#503)
undefined
  • Resolved memory leak in WebSocket connections affecting long-running sessions (#489)
  • Fixed race condition in concurrent API requests that caused data inconsistency (#503)
undefined

Bad Examples

反面示例

markdown
undefined
markdown
undefined

Added

Added

  • Added stuff
  • New feature
  • Added stuff
  • New feature

Fixed

Fixed

  • Fixed bug
  • Updates
undefined
  • Fixed bug
  • Updates
undefined

Version Suggestion Algorithm

版本号建议算法

If breaking changes detected:
  MAJOR++, MINOR=0, PATCH=0
Else if new features:
  MINOR++, PATCH=0
Else if only fixes:
  PATCH++
如果检测到重大变更：
  MAJOR++, MINOR=0, PATCH=0
否则如果有新功能：
  MINOR++, PATCH=0
否则如果只有修复：
  PATCH++

Release Checklist

发布检查清单

Before publishing release:
  • Review all commits since last release
  • Identify breaking changes
  • Categorize changes properly
  • Update CHANGELOG.md
  • Write release notes
  • Update version in package.json/pyproject.toml
  • Create git tag
  • Push tag to trigger CI/CD
  • Publish to package registry (npm, PyPI, etc.)
  • Create GitHub release with notes
  • Announce on relevant channels
发布前需完成：
  • 审核上次发布以来的所有提交记录
  • 识别重大变更
  • 正确分类变更内容
  • 更新CHANGELOG.md
  • 撰写发布说明
  • 更新package.json/pyproject.toml中的版本号
  • 创建Git标签
  • 推送标签触发CI/CD流程
  • 发布到包管理仓库（npm、PyPI等）
  • 创建带说明的GitHub发布
  • 在相关渠道发布公告

Output Checklist

输出检查清单

Every changelog generation should provide:
  • Formatted CHANGELOG.md following Keep a Changelog
  • Release notes draft (user-friendly)
  • Semantic version suggestion (X.Y.Z)
  • Breaking changes clearly marked
  • Migration guide for breaking changes
  • Git tag command to run
  • Links to compare view
每次变更日志生成应包含：
  • 遵循Keep a Changelog格式的CHANGELOG.md
  • 用户友好的发布说明草稿
  • 语义化版本号建议（X.Y.Z）
  • 清晰标记的重大变更
  • 重大变更的迁移指南
  • 可执行的Git标签命令
  • 版本对比链接