Back to Details

conventional-commits

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Conventional Commits

Conventional Commits

Format all commit messages according to the Conventional Commits specification. This enables automated changelog generation, semantic versioning, and better commit history.
所有提交信息均需按照Conventional Commits规范进行格式化。这能实现自动化变更日志生成、语义化版本控制，并优化提交历史的可读性。

Format Structure

格式结构

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

提交类型

Required Types

必填类型

  • feat:
     - A new feature (correlates with MINOR in Semantic Versioning)
  • fix:
     - A bug fix (correlates with PATCH in Semantic Versioning)
  • feat:
     - 新增功能（对应语义化版本控制中的MINOR版本更新）
  • fix:
     - 修复Bug（对应语义化版本控制中的PATCH版本更新）

Common Additional Types

常见扩展类型

  • docs:
     - Documentation only changes
  • style:
     - Code style changes (formatting, missing semicolons, etc.)
  • refactor:
     - Code refactoring without bug fixes or new features
  • perf:
     - Performance improvements
  • test:
     - Adding or updating tests
  • build:
     - Build system or external dependencies changes
  • ci:
     - CI/CD configuration changes
  • chore:
     - Other changes that don't modify src or test files
  • revert:
     - Reverts a previous commit
  • docs:
     - 仅修改文档
  • style:
     - 代码样式变更（如格式化、补充分号等，不涉及逻辑修改）
  • refactor:
     - 代码重构，既不修复Bug也不新增功能
  • perf:
     - 性能优化
  • test:
     - 添加或更新测试用例
  • build:
     - 构建系统或外部依赖变更
  • ci:
     - CI/CD配置变更
  • chore:
     - 其他不修改源码或测试文件的变更
  • revert:
     - 回滚之前的提交

Scope

作用域

An optional scope provides additional contextual information about the section of the codebase:
feat(parser): add ability to parse arrays
fix(auth): resolve token expiration issue
docs(readme): update installation instructions
可选的作用域用于提供代码库中变更部分的额外上下文信息：
feat(parser): add ability to parse arrays
fix(auth): resolve token expiration issue
docs(readme): update installation instructions

Description

描述信息

  • Must immediately follow the colon and space after the type/scope
  • Use imperative mood ("add feature" not "added feature" or "adds feature")
  • Don't capitalize the first letter
  • No period at the end
  • Hard limit: 72 characters (including type and scope)
  • Recommended: 50 characters or fewer for better readability
  • 必须紧跟在类型/作用域后的冒号和空格之后
  • 使用祈使语气（如"add feature"，而非"added feature"或"adds feature"）
  • 首字母无需大写
  • 结尾不加句号
  • 硬限制：最多72个字符（包含类型和作用域）
  • 推荐：控制在50个字符以内，提升可读性

Body

正文部分

  • Optional longer description providing additional context
  • Must begin one blank line after the description
  • Can consist of multiple paragraphs
  • Explain the "what" and "why" of the change, not the "how"
  • 可选的详细描述，用于提供额外上下文
  • 必须在描述信息后空一行开始
  • 可包含多个段落
  • 说明变更的“内容”和“原因”，而非“实现方式”

Breaking Changes

破坏性变更

Breaking changes can be indicated in two ways:
破坏性变更可通过两种方式标记：

1. Using 
!
in the type/scope

1. 在类型/作用域后添加
!

feat!: send an email to the customer when a product is shipped
feat(api)!: send an email to the customer when a product is shipped
feat!: send an email to the customer when a product is shipped
feat(api)!: send an email to the customer when a product is shipped

2. Using BREAKING CHANGE footer

2. 使用BREAKING CHANGE页脚

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files
feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

3. Both methods

3. 同时使用两种方式

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.
chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Examples

示例

Simple feature

简单功能提交

feat: add user authentication
feat: add user authentication

Feature with scope

带作用域的功能提交

feat(auth): add OAuth2 support
feat(auth): add OAuth2 support

Bug fix with body

带正文的Bug修复提交

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Breaking change

破坏性变更提交

feat!: migrate to new API client

BREAKING CHANGE: The API client interface has changed. All methods now
return Promises instead of using callbacks.
feat!: migrate to new API client

BREAKING CHANGE: The API client interface has changed. All methods now
return Promises instead of using callbacks.

Documentation update

文档更新提交

docs: correct spelling of CHANGELOG
docs: correct spelling of CHANGELOG

Multi-paragraph body with footers

带多段正文和页脚的提交

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123
fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

Guidelines

规范准则

  1. Always use a type - Every commit must start with a type followed by a colon and space
  2. Use imperative mood - Write as if completing the sentence "If applied, this commit will..."
  3. Be specific - The description should clearly communicate what changed
  4. Keep it focused - One logical change per commit
  5. Use scopes when helpful - Scopes help categorize changes within a codebase
  6. Document breaking changes - Always indicate breaking changes clearly
  1. 必须指定类型 - 每个提交必须以类型开头，后跟冒号和空格
  2. 使用祈使语气 - 撰写时可设想完成句子：“若应用此提交，将……”
  3. 描述具体 - 描述信息需清晰传达变更内容
  4. 聚焦单一变更 - 每个提交对应一个逻辑变更
  5. 合理使用作用域 - 作用域有助于对代码库内的变更进行分类
  6. 明确标记破坏性变更 - 必须清晰标注所有破坏性变更

Semantic Versioning Correlation

与语义化版本控制的关联

  • fix:
     → PATCH version bump (1.0.0 → 1.0.1)
  • feat:
     → MINOR version bump (1.0.0 → 1.1.0)
  • BREAKING CHANGE → MAJOR version bump (1.0.0 → 2.0.0)
  • fix:
     → PATCH版本更新（1.0.0 → 1.0.1）
  • feat:
     → MINOR版本更新（1.0.0 → 1.1.0）
  • BREAKING CHANGE → MAJOR版本更新（1.0.0 → 2.0.0）

When to Use

使用场景

Use this format for:
  • All git commits
  • Commit message generation
  • Pull request merge commits
  • When the user asks about commit messages or git commits
以下场景需遵循此格式：
  • 所有Git提交
  • 提交信息生成
  • 拉取请求合并提交
  • 当用户咨询提交信息或Git提交相关问题时

Common Mistakes to Avoid

常见错误规避

❌ 
Added new feature
(past tense, capitalized) ✅ 
feat: add new feature
(imperative, lowercase)
❌ 
fix: bug
(too vague) ✅ 
fix: resolve null pointer exception in user service
❌ 
feat: add feature
(redundant) ✅ 
feat: add user profile page
❌ 
feat: Added OAuth support.
(past tense, period) ✅ 
feat: add OAuth support
❌ 
Added new feature
（过去式、首字母大写） ✅ 
feat: add new feature
（祈使语气、小写）
❌ 
fix: bug
（描述过于模糊） ✅ 
fix: resolve null pointer exception in user service
❌ 
feat: add feature
（表述冗余） ✅ 
feat: add user profile page
❌ 
feat: Added OAuth support.
（过去式、结尾加句号） ✅ 
feat: add OAuth support