Back to Details

changelog-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Changelog Writer

变更日志编写指南

Create and maintain changelogs following industry standards.
遵循行业标准创建并维护变更日志。

When to Use

使用场景

  • Preparing a new release
  • Documenting recent changes
  • Creating initial changelog
  • Migrating to standard format
  • 准备新版本发布
  • 记录近期变更
  • 创建初始变更日志
  • 迁移至标准格式

Changelog Format

变更日志格式

Following Keep a Changelog:
markdown
undefined
遵循Keep a Changelog:
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 description
  • New feature description

Changed

Changed

  • Modified behavior description
  • Modified behavior description

Deprecated

Deprecated

  • Soon-to-be removed feature
  • Soon-to-be removed feature

Removed

Removed

  • Removed feature description
  • Removed feature description

Fixed

Fixed

  • Bug fix description
  • Bug fix description

Security

Security

  • Security fix description
  • Security fix description

[1.0.0] - 2026-01-15

[1.0.0] - 2026-01-15

Added

Added

  • Initial release
  • Core functionality
undefined
  • Initial release
  • Core functionality
undefined

Change Categories

变更分类

CategoryUse For
AddedNew features
ChangedChanges in existing functionality
DeprecatedFeatures to be removed in future
RemovedFeatures removed in this release
FixedBug fixes
SecuritySecurity vulnerability fixes
分类适用场景
Added新功能
Changed现有功能变更
Deprecated即将移除的功能
Removed本版本移除的功能
FixedBug修复
Security安全漏洞修复

Writing Good Entries

编写优质条目

Do

正确示例

markdown
undefined
markdown
undefined

Added

Added

  • Add user authentication with JWT tokens
  • Add rate limiting (100 requests/minute per IP)
  • Add CSV export for reports
  • Add user authentication with JWT tokens
  • Add rate limiting (100 requests/minute per IP)
  • Add CSV export for reports

Fixed

Fixed

  • Fix memory leak when processing large files (#234)
  • Fix incorrect timezone handling in date picker
undefined
  • Fix memory leak when processing large files (#234)
  • Fix incorrect timezone handling in date picker
undefined

Don't

错误示例

markdown
undefined
markdown
undefined

Added

Added

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

Fixed

Fixed

  • Fixed bug
  • Fix issue
undefined
  • Fixed bug
  • Fix issue
undefined

Entry Guidelines

条目编写准则

Be Specific

内容具体

markdown
undefined
markdown
undefined

Bad

不良示例

  • Fixed a bug
  • Fixed a bug

Good

良好示例

  • Fix crash when uploading files larger than 10MB (#156)
undefined
  • Fix crash when uploading files larger than 10MB (#156)
undefined

Include Context

包含上下文

markdown
undefined
markdown
undefined

Bad

不良示例

  • Changed the API
  • Changed the API

Good

良好示例

  • Change 
    /users
    endpoint to require authentication (BREAKING)
undefined
  • Change 
    /users
    endpoint to require authentication (BREAKING)
undefined

Reference Issues/PRs

关联问题/PR

markdown
- Add dark mode support (#234)
- Fix memory leak in image processor (fixes #189)
markdown
- Add dark mode support (#234)
- Fix memory leak in image processor (fixes #189)

Indicate Breaking Changes

标记破坏性变更

markdown
undefined
markdown
undefined

Changed

Changed

  • BREAKING: Rename 
    getUser()
    to 
    fetchUser()
    for consistency
  • BREAKING: Remove deprecated 
    v1
    API endpoints
undefined
  • BREAKING: Rename 
    getUser()
    to 
    fetchUser()
    for consistency
  • BREAKING: Remove deprecated 
    v1
    API endpoints
undefined

Conventional Commits to Changelog

Conventional Commits 映射至变更日志

Map commit types to changelog categories:
Commit TypeChangelog Category
feat:
Added
fix:
Fixed
docs:
(usually not included)
style:
(usually not included)
refactor:
Changed (if user-facing)
perf:
Changed
test:
(usually not included)
chore:
(usually not included)
BREAKING CHANGE:
Changed/Removed
将提交类型映射到变更日志分类：
提交类型变更日志分类
feat:
Added
fix:
Fixed
docs:
(通常不包含)
style:
(通常不包含)
refactor:
Changed（若面向用户）
perf:
Changed
test:
(通常不包含)
chore:
(通常不包含)
BREAKING CHANGE:
Changed/Removed

Example Commits to Entries

提交示例转条目

feat: add user profile page
fix: resolve login timeout issue (#123)
feat!: change authentication to OAuth 2.0
Becomes:
markdown
undefined
feat: add user profile page
fix: resolve login timeout issue (#123)
feat!: change authentication to OAuth 2.0
转换为：
markdown
undefined

Added

Added

  • Add user profile page
  • Add user profile page

Changed

Changed

  • BREAKING: Change authentication to OAuth 2.0
  • BREAKING: Change authentication to OAuth 2.0

Fixed

Fixed

  • Resolve login timeout issue (#123)
undefined
  • Resolve login timeout issue (#123)
undefined

Version Numbering

版本号规则

Following Semantic Versioning:
MAJOR.MINOR.PATCH

1.0.0 → 1.0.1  (patch: bug fixes)
1.0.1 → 1.1.0  (minor: new features, backward compatible)
1.1.0 → 2.0.0  (major: breaking changes)
遵循Semantic Versioning:
MAJOR.MINOR.PATCH

1.0.0 → 1.0.1  (补丁版本：Bug修复)
1.0.1 → 1.1.0  (次版本：新增功能，向后兼容)
1.1.0 → 2.0.0  (主版本：破坏性变更)

When to Bump

版本升级场景

Change TypeVersion Bump
Bug fix (backward compatible)PATCH
New feature (backward compatible)MINOR
Breaking changeMAJOR
Security fixPATCH (or MINOR if new feature)
变更类型版本升级类型
向后兼容的Bug修复PATCH
向后兼容的新功能MINOR
破坏性变更MAJOR
安全修复PATCH（若涉及新功能则为MINOR）

Release Checklist

发布检查清单

When preparing a release:
  1. Move items from 
    [Unreleased]
    to new version section
  2. Add release date: 
    ## [1.2.0] - 2026-01-15
  3. Update comparison links at bottom
  4. Remove empty categories
  5. Review for clarity and completeness
  6. Commit changelog with version bump
准备发布时：
  1. 将
    [Unreleased]
    中的条目移至新版本章节
  2. 添加发布日期：
    ## [1.2.0] - 2026-01-15
  3. 更新底部的对比链接
  4. 移除空分类
  5. 检查内容的清晰度与完整性
  6. 提交变更日志并升级版本号

Automation Tools

自动化工具

Conventional Changelog

Conventional Changelog

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

Release Please

Release Please

yaml
undefined
yaml
undefined

.github/workflows/release.yml

.github/workflows/release.yml

  • uses: google-github-actions/release-please-action@v4 with: release-type: node
undefined
  • uses: google-github-actions/release-please-action@v4 with: release-type: node
undefined

Changesets

Changesets

bash
npx changeset        # Create changeset
npx changeset version # Update versions
bash
npx changeset        # 创建变更记录
npx changeset version # 更新版本号

Template: Initial 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]

[0.1.0] - YYYY-MM-DD

[0.1.0] - YYYY-MM-DD

Added

Added

  • Initial release
  • [List initial features]
undefined
  • Initial release
  • [List initial features]
undefined