conventional-commits

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Conventional Commits

Conventional Commits 语义化提交规范

Write standardized, semantic commit messages that enable automated versioning and changelog generation.

编写标准化的语义化提交信息，支持自动版本控制和变更日志生成。

Core Workflow

核心工作流程

Analyze changes: Review staged files and modifications
Determine type: Select appropriate commit type (feat, fix, etc.)
Identify scope: Optional component/module affected
Write description: Concise summary in imperative mood
Add body: Optional detailed explanation
Include footer: Breaking changes, issue references

分析变更：查看暂存文件和修改内容
确定类型：选择合适的提交类型（feat、fix等）
识别作用域：可选，指受影响的组件/模块
编写描述：使用祈使语气的简洁摘要
添加正文：可选，详细解释变更
包含脚注：破坏性变更、问题引用等

Commit Message Format

提交信息格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

<类型>[可选作用域]: <描述>

[可选正文]

[可选脚注]

Commit Types

提交类型

Type	Description	Semver	Example
`feat`	New feature	MINOR	`feat: add user authentication`
`fix`	Bug fix	PATCH	`fix: resolve login redirect loop`
`docs`	Documentation only	-	`docs: update API reference`
`style`	Formatting, whitespace	-	`style: fix indentation in utils`
`refactor`	Code change, no feature/fix	-	`refactor: extract validation logic`
`perf`	Performance improvement	PATCH	`perf: optimize database queries`
`test`	Adding/fixing tests	-	`test: add unit tests for auth`
`build`	Build system, dependencies	-	`build: upgrade to Node 20`
`ci`	CI/CD configuration	-	`ci: add GitHub Actions workflow`
`chore`	Maintenance tasks	-	`chore: update .gitignore`
`revert`	Revert previous commit	-	`revert: undo feature flag change`

类型	描述	版本规则	示例
`feat`	新功能	MINOR	`feat: add user authentication`
`fix`	修复Bug	PATCH	`fix: resolve login redirect loop`
`docs`	仅文档修改	-	`docs: update API reference`
`style`	格式调整、空白字符修改	-	`style: fix indentation in utils`
`refactor`	代码重构，不新增功能或修复Bug	-	`refactor: extract validation logic`
`perf`	性能优化	PATCH	`perf: optimize database queries`
`test`	添加/修复测试用例	-	`test: add unit tests for auth`
`build`	构建系统、依赖修改	-	`build: upgrade to Node 20`
`ci`	CI/CD配置修改	-	`ci: add GitHub Actions workflow`
`chore`	维护任务	-	`chore: update .gitignore`
`revert`	回滚之前的提交	-	`revert: undo feature flag change`

Scopes

作用域

Scopes indicate the area of the codebase affected:

bash

undefined

作用域用于标记代码库中受影响的区域：

bash

undefined

Component/module scopes

组件/模块作用域

feat(auth): add OAuth2 support fix(api): handle timeout errors docs(readme): add installation steps

File-based scopes

文件级作用域

style(eslint): update linting rules build(docker): optimize image size

Layer scopes

分层作用域

refactor(service): extract user service test(e2e): add checkout flow tests

undefined

refactor(service): extract user service test(e2e): add checkout flow tests

undefined

Breaking Changes

破坏性变更

Mark breaking changes with

BREAKING CHANGE

footer:

bash

undefined

使用

或

BREAKING CHANGE

脚注标记破坏性变更：

bash

undefined

Using ! notation

使用!标记

feat(api)!: change response format to JSON:API

Using footer

使用脚注

feat(api): change response format

BREAKING CHANGE: Response now follows JSON:API specification. Clients must update their parsers.

undefined

feat(api): change response format

BREAKING CHANGE: Response now follows JSON:API specification. Clients must update their parsers.

undefined

Commit Message Examples

提交信息示例

Simple Feature

简单功能提交

feat: add dark mode toggle

feat: add dark mode toggle

Feature with Scope

带作用域的功能提交

feat(ui): add dark mode toggle to settings page

feat(ui): add dark mode toggle to settings page

Bug Fix with Issue Reference

关联问题的Bug修复提交

fix(auth): resolve session expiration race condition

The session refresh was racing with the expiration check,
causing intermittent logouts.

Fixes #234

fix(auth): resolve session expiration race condition

The session refresh was racing with the expiration check,
causing intermittent logouts.

Fixes #234

Breaking Change

破坏性变更提交

feat(api)!: migrate to v2 response format

BREAKING CHANGE: All API responses now use camelCase keys
instead of snake_case. Update client parsers accordingly.

Migration guide: https://docs.example.com/v2-migration

feat(api)!: migrate to v2 response format

BREAKING CHANGE: All API responses now use camelCase keys
instead of snake_case. Update client parsers accordingly.

Migration guide: https://docs.example.com/v2-migration

Multiple Footers

多脚注提交

fix(payments): correct tax calculation for EU customers

Updated tax calculation to use customer's billing country
instead of shipping country for digital goods.

Fixes #456
Reviewed-by: Alice
Co-authored-by: Bob <bob@example.com>

fix(payments): correct tax calculation for EU customers

Updated tax calculation to use customer's billing country
instead of shipping country for digital goods.

Fixes #456
Reviewed-by: Alice
Co-authored-by: Bob <bob@example.com>

Revert Commit

回滚提交

revert: feat(auth): add OAuth2 support

This reverts commit abc123def456.

Reason: OAuth provider has rate limiting issues in production.
Will re-implement with proper caching.

revert: feat(auth): add OAuth2 support

This reverts commit abc123def456.

Reason: OAuth provider has rate limiting issues in production.
Will re-implement with proper caching.

Description Guidelines

描述信息指南

Do

建议做法

Use imperative mood: "add" not "added" or "adds"
Keep under 72 characters
Start with lowercase
No period at the end
Be specific and concise

使用祈使语气：用“add”而非“added”或“adds”
长度控制在72字符以内
首字母小写
结尾不加句号
描述具体简洁

Don't

避免做法

"Fixed bug" (too vague)
"Updated stuff" (not descriptive)
"WIP" (commit when ready)
"misc changes" (split into separate commits)

过于模糊的描述：如“Fixed bug”
笼统的表述：如“Updated stuff”
包含“WIP”（完成后再提交）
“misc changes”（拆分到多个提交中）

Good Examples

优秀示例

bash

feat: add email verification flow
fix: prevent duplicate form submissions
refactor: extract payment processing to service
perf: cache user preferences in memory
docs: add API authentication examples

bash

feat: add email verification flow
fix: prevent duplicate form submissions
refactor: extract payment processing to service
perf: cache user preferences in memory
docs: add API authentication examples

Bad Examples

反面示例

bash

undefined

bash

undefined

Too vague

过于模糊

fix: fixed it update: updates

Wrong tense

时态错误

feat: added new feature fix: fixes the bug

Too long

过长

feat: add a new feature that allows users to export their data in multiple formats including CSV, JSON, and XML

undefined

feat: add a new feature that allows users to export their data in multiple formats including CSV, JSON, and XML

undefined

Body Guidelines

正文信息指南

When to include a body:

Changes need context or explanation
Complex logic that isn't self-evident
Breaking changes require migration info
Multiple related changes in one commit

fix(cache): invalidate user cache on profile update

Previously, profile updates were not reflected until cache expiry.
This caused confusion when users updated their avatar and didn't
see the change immediately.

The fix adds cache invalidation after successful profile updates
and ensures CDN purge for static assets.

以下情况建议添加正文：

变更需要额外的上下文或解释
逻辑复杂，无法通过描述自行说明
破坏性变更需要迁移说明
单次提交包含多个相关变更

fix(cache): invalidate user cache on profile update

Previously, profile updates were not reflected until cache expiry.
This caused confusion when users updated their avatar and didn't
see the change immediately.

The fix adds cache invalidation after successful profile updates
and ensures CDN purge for static assets.

Footer Tokens

脚注标记

Token	Purpose	Example
`Fixes`	Closes issue	`Fixes #123`
`Closes`	Closes issue	`Closes #456`
`Refs`	References issue	`Refs #789`
`BREAKING CHANGE`	Breaking change	`BREAKING CHANGE: description`
`Reviewed-by`	Reviewer credit	`Reviewed-by: Name`
`Co-authored-by`	Co-author credit	`Co-authored-by: Name <email>`

标记	用途	示例
`Fixes`	关联并关闭问题	`Fixes #123`
`Closes`	关联并关闭问题	`Closes #456`
`Refs`	关联问题	`Refs #789`
`BREAKING CHANGE`	标记破坏性变更	`BREAKING CHANGE: description`
`Reviewed-by`	标记审核人	`Reviewed-by: Name`
`Co-authored-by`	标记共同作者	`Co-authored-by: Name <email>`

Integration with Tooling

工具集成

Commitlint Configuration

Commitlint配置

javascript

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat', 'fix', 'docs', 'style', 'refactor',
        'perf', 'test', 'build', 'ci', 'chore', 'revert'
      ]
    ],
    'scope-case': [2, 'always', 'kebab-case'],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100]
  }
};

javascript

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat', 'fix', 'docs', 'style', 'refactor',
        'perf', 'test', 'build', 'ci', 'chore', 'revert'
      ]
    ],
    'scope-case': [2, 'always', 'kebab-case'],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100]
  }
};

Husky Pre-commit Hook

Husky提交前钩子

bash

undefined

bash

undefined

.husky/commit-msg

#!/bin/sh . "$(dirname "$0")/_/husky.sh" npx --no-install commitlint --edit "$1"

undefined

#!/bin/sh . "$(dirname "$0")/_/husky.sh" npx --no-install commitlint --edit "$1"

undefined

Package.json Setup

Package.json配置

json

{
  "devDependencies": {
    "@commitlint/cli": "^18.0.0",
    "@commitlint/config-conventional": "^18.0.0",
    "husky": "^8.0.0"
  },
  "scripts": {
    "prepare": "husky install"
  }
}

json

{
  "devDependencies": {
    "@commitlint/cli": "^18.0.0",
    "@commitlint/config-conventional": "^18.0.0",
    "husky": "^8.0.0"
  },
  "scripts": {
    "prepare": "husky install"
  }
}

Semantic Release Integration

Semantic Release集成

Conventional commits enable automated versioning:

yaml

undefined

语义化提交支持自动版本控制：

yaml

undefined

.releaserc.yml

branches:

main plugins:
"@semantic-release/commit-analyzer"
"@semantic-release/release-notes-generator"
"@semantic-release/changelog"
"@semantic-release/npm"
"@semantic-release/git"

undefined

branches:

main plugins:
"@semantic-release/commit-analyzer"
"@semantic-release/release-notes-generator"
"@semantic-release/changelog"
"@semantic-release/npm"
"@semantic-release/git"

undefined

Version Bumping Rules

版本升级规则

Commit Type	Version Bump	Example
`feat`	Minor (0.X.0)	1.2.0 → 1.3.0
`fix`	Patch (0.0.X)	1.2.0 → 1.2.1
`perf`	Patch (0.0.X)	1.2.0 → 1.2.1
`BREAKING CHANGE`	Major (X.0.0)	1.2.0 → 2.0.0
Others	No bump	1.2.0 → 1.2.0

提交类型	版本升级	示例
`feat`	次版本号（0.X.0）	1.2.0 → 1.3.0
`fix`	修订号（0.0.X）	1.2.0 → 1.2.1
`perf`	修订号（0.0.X）	1.2.0 → 1.2.1
`BREAKING CHANGE`	主版本号（X.0.0）	1.2.0 → 2.0.0
其他类型	不升级	1.2.0 → 1.2.0

Commit Message Generator

提交信息生成步骤

When analyzing changes, generate a commit message:

bash

undefined

分析变更时，可按以下步骤生成提交信息：

bash

undefined

1. Check staged changes

1. 查看暂存的变更

git diff --cached --name-only

2. Analyze change type

2. 判断变更类型

- New files = likely feat

- 新增文件 → 通常是feat

- Modified test files = test

修改测试文件 → test

- Modified docs = docs

修改文档 → docs

- Bug-related keywords = fix

包含Bug相关关键词 → fix

3. Identify scope from path

3. 根据路径确定作用域

src/components/Button.tsx → components or ui

src/components/Button.tsx → components或ui

src/services/auth.ts → auth or services

src/services/auth.ts → auth或services

4. Generate message

4. 生成提交信息

feat(ui): add loading state to Button component

undefined

feat(ui): add loading state to Button component

undefined

Best Practices

最佳实践

One logical change per commit: Don't mix features with fixes
Commit early, commit often: Small, focused commits
Write for reviewers: Messages should explain why, not just what
Reference issues: Link to tickets/issues when applicable
Use scopes consistently: Establish team conventions
Review before committing:
```
git diff --cached
```
to verify changes

单次提交对应一个逻辑变更：不要混合功能和Bug修复
早提交、常提交：保持提交小而聚焦
为审核者编写信息：信息应解释原因，而非仅说明内容
关联问题：适用时链接到工单/问题
一致使用作用域：建立团队约定
提交前检查：使用
```
git diff --cached
```
验证变更

Output Checklist

提交信息检查清单

Every commit message should:

Start with valid type (feat, fix, docs, etc.)
Use imperative mood in description
Keep description under 72 characters
Include scope when applicable
Mark breaking changes with
```
!
```
or footer
Reference related issues in footer
Provide body for complex changes
Follow team's scope conventions

每条提交信息应满足：

以有效的类型开头（feat、fix、docs等）
描述使用祈使语气
描述长度不超过72字符
适用时包含作用域
使用
```
!
```
或脚注标记破坏性变更
脚注中关联相关问题
复杂变更包含正文说明
遵循团队的作用域约定