conventional-commits

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Format

格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

type: lowercase noun (see table below)
scope: optional noun in parentheses describing the affected section, e.g.
```
feat(auth):
```
description: imperative, present tense, no period at end, immediately after
```
": "
```
body: free-form; begins one blank line after description
footers: one blank line after body; follow git trailer format (
```
Token: value
```
or
```
Token #value
```
)

<type>[可选范围]: <描述>

[可选正文]

[可选页脚]

type: 小写名词（见下表）
scope: 可选的括号内名词，描述受影响的部分，例如
```
feat(auth):
```
description: 祈使语气、现在时，结尾无句号，紧跟在
```
": "
```
之后
body: 自由格式；在描述后空一行开始
footers: 在正文后空一行；遵循Git trailer格式（
```
Token: value
```
或
```
Token #value
```
）

Types and SemVer impact

类型与SemVer影响

Type	Use for	SemVer
`feat`	New feature	MINOR
`fix`	Bug fix	PATCH
`docs`	Documentation only	none
`style`	Formatting, whitespace (no logic change)	none
`refactor`	Code restructure (not a fix or feature)	none
`perf`	Performance improvement	none
`test`	Adding or fixing tests	none
`build`	Build system, dependencies (npm, gradle…)	none
`ci`	CI configuration (GitHub Actions, CircleCI…)	none
`chore`	Maintenance not fitting above types	none
`revert`	Reverts a previous commit	none

Any type +

BREAKING CHANGE

→ MAJOR.

类型	适用场景	SemVer 版本更新
`feat`	新功能	MINOR
`fix`	修复Bug	PATCH
`docs`	仅修改文档	无
`style`	格式调整、空白字符修改（无逻辑变更）	无
`refactor`	代码重构（不是修复Bug或新增功能）	无
`perf`	性能优化	无
`test`	添加或修复测试	无
`build`	构建系统、依赖项（npm、gradle等）	无
`ci`	CI配置（GitHub Actions、CircleCI等）	无
`chore`	不属于上述类型的维护工作	无
`revert`	回滚之前的提交	无

任何类型 +

BREAKING CHANGE

→ MAJOR（主版本更新）。

Breaking changes

破坏性变更

Two ways to signal a breaking change (can combine both):

1.
!
after type/scope (visible at a glance):

feat(api)!: remove deprecated v1 endpoints

2.
BREAKING CHANGE:
footer (required if you need a description):

feat: allow config object to extend other configs

BREAKING CHANGE: `extends` key now used for extending config files

Both together:

chore!: drop support for Node 6

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

有两种方式标记破坏性变更（可同时使用）：

1. 在类型/范围后添加
!
（一眼可见）：

feat(api)!: 移除已废弃的v1端点

2. 使用
BREAKING CHANGE:
页脚（需要描述时必填）：

feat: 允许配置对象继承其他配置

BREAKING CHANGE: 现在使用`extends`字段来继承配置文件

两者结合：

chore!: 停止支持Node 6

BREAKING CHANGE: 使用了Node 6不支持的JavaScript特性。

Examples

示例

Simple fix:

fix: prevent racing of requests

Feature with scope:

feat(lang): add Polish language

Fix with body and 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

Revert with footer references:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

Docs with no body:

docs: correct spelling of CHANGELOG

简单修复：

fix: 防止请求竞态

带范围的功能：

feat(lang): 添加波兰语支持

带正文和页脚的修复：

fix: 防止请求竞态

引入请求ID和最新请求的引用。忽略来自非最新请求的响应。

移除用于缓解竞态问题的超时机制，现在该机制已过时。

Reviewed-by: Z
Refs: #123

带页脚引用的回滚：

revert: 让我们永远不再提及面条事件

Refs: 676104e, a215868

无正文的文档修改：

docs: 修正CHANGELOG的拼写错误

Non-obvious rules

非显式规则

NEVER add
```
Co-Authored-By
```
trailers to commit messages. This project does not use authorship footers.
Types are case-insensitive in parsing, but
```
BREAKING CHANGE
```
footer token must be uppercase.
```
BREAKING-CHANGE
```
(hyphen) is a valid synonym for
```
BREAKING CHANGE
```
in footers.
Footer tokens use
```
-
```
instead of spaces (e.g.
```
Reviewed-by
```
), except
```
BREAKING CHANGE
```
.
Footer separator is either
```
": "
```
(colon-space) or
```
" #"
```
(space-hash for issue refs):
```
Refs #123
```
.
A footer value may span multiple lines; parsing stops at the next valid
```
Token: 
```
or
```
Token #
```
pair.
When a commit fits multiple types, split into multiple commits instead of picking one.
Wrong type used before merge? Ask the developer to fix manually with an interactive rebase. Claude Code cannot run interactive commands. After release, the commit is simply missed by automation tools — not catastrophic.
Squash workflows: lead maintainer can rewrite messages at merge time; contributors don't need to follow the spec perfectly on every WIP commit.

切勿在提交信息中添加
```
Co-Authored-By
```
标记。本项目不使用作者身份页脚。
解析时类型不区分大小写，但
```
BREAKING CHANGE
```
页脚标记必须大写。
页脚中
```
BREAKING-CHANGE
```
（连字符形式）是
```
BREAKING CHANGE
```
的有效同义词。
页脚标记使用
```
-
```
代替空格（例如
```
Reviewed-by
```
），除了
```
BREAKING CHANGE
```
。
页脚分隔符可以是
```
": "
```
（冒号加空格）或
```
" #"
```
（空格加井号，用于引用议题）：
```
Refs #123
```
。
页脚值可以跨多行；解析会在遇到下一个有效的
```
Token: 
```
或
```
Token #
```
对时停止。
当一个提交符合多种类型时，应拆分为多个提交而非选择其中一种。
合并前使用了错误的类型？请开发者通过交互式变基手动修正。Claude Code无法运行交互式命令。发布后，自动化工具会遗漏该提交，但不会造成严重问题。
压缩合并工作流：首席维护者可以在合并时重写提交信息；贡献者无需在每个WIP（进行中）提交中完美遵循规范。

Choosing the right type

选择合适的类型

Is it a new user-facing capability?         → feat
Is it fixing incorrect behavior?            → fix
Is it changing docs/comments only?          → docs
Is it improving speed/memory?               → perf
Is it reorganizing code (no behavior Δ)?    → refactor
Is it adding/fixing tests only?             → test
Is it CI pipeline config?                   → ci
Is it build tooling or dependency updates?  → build
Is it undoing a previous commit?            → revert
Everything else (scripts, config, etc.)?    → chore

是否是面向用户的新功能？         → feat
是否是修复错误行为？            → fix
是否仅修改文档/注释？          → docs
是否是提升速度/内存使用？               → perf
是否是代码重组（无行为变化）？    → refactor
是否仅添加/修复测试？             → test
是否是CI流水线配置？                   → ci
是否是构建工具或依赖项更新？  → build
是否是回滚之前的提交？            → revert
其他所有情况（脚本、配置等）？    → chore

SemVer cheatsheet

SemVer速查表

fix

→PATCH,

feat

→MINOR,

BREAKING CHANGE

→MAJOR

fix

→PATCH（补丁版本）,

feat

→MINOR（次版本）,

BREAKING CHANGE

→MAJOR（主版本）