conventional-git-commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Conventional Git Commit

符合规范的Git提交

MANDATORY RULE: Every git commit message in this project MUST follow the Conventional Commits 1.0.0 specification. No exceptions. A commit with a non-conforming message MUST be rejected and rewritten before proceeding.

Produces git commit messages that conform to the Conventional Commits 1.0.0 specification — a lightweight, machine-readable convention that maps directly to Semantic Versioning.

强制规则：本项目中的每一条git提交信息都必须遵循Conventional Commits 1.0.0规范，无一例外。提交信息不符合规范的提交必须被驳回并重新编写后才能继续。

生成符合Conventional Commits 1.0.0规范的git提交信息——这是一种轻量的、机器可读的约定，可直接映射到Semantic Versioning（语义化版本控制）。

Commit Message Structure

提交信息结构

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Every part of this structure is defined by strict rules:

type — Required. A noun indicating the category of change.
scope — Optional. A noun in parentheses narrowing the affected area, e.g.
```
fix(parser):
```
.
!
— Optional. Appended immediately before
```
:
```
to flag a breaking change.
description — Required. A short, imperative-mood summary immediately after the colon+space.
body — Optional. One blank line after the description; free-form paragraphs.
footers — Optional. One blank line after the body;
```
Token: value
```
or
```
Token #value
```
pairs.

<type>[可选 scope]: <description>

[可选 body]

[可选 footer(s)]

该结构的每一部分都有严格的规则定义：

type — 必填。表示变更类别的名词。
scope — 可选。用括号包裹的名词，用于缩小变更影响范围，例如
```
fix(parser):
```
。
!
— 可选。直接追加在
```
:
```
之前，用于标记破坏性变更。
description — 必填。冒号加空格后紧跟的简短、祈使语气摘要。
body — 可选。与description之间空一行；格式自由的段落。
footers — 可选。与body之间空一行；采用
```
Token: value
```
或
```
Token #value
```
的键值对格式。

Core Types

核心类型

Type	SemVer impact	When to use
`feat`	MINOR	Introduces a new feature
`fix`	PATCH	Patches a bug
`docs`	none	Documentation changes only
`style`	none	Formatting, whitespace, missing semicolons
`refactor`	none	Code change that is neither a fix nor a feature
`perf`	none	Performance improvement
`test`	none	Adding or correcting tests
`build`	none	Build system or external dependency changes
`ci`	none	CI/CD configuration changes
`chore`	none	Routine tasks, maintenance, tooling
`revert`	varies	Reverts a previous commit

Only

feat

and

fix

have implicit SemVer meaning. All others carry no automatic version bump unless accompanied by a breaking change marker.

类型	SemVer影响	使用场景
`feat`	MINOR（次版本号）	引入新功能
`fix`	PATCH（修订号）	修复bug
`docs`	无	仅修改文档
`style`	无	格式调整、空格修正、补充分号等
`refactor`	无	既不是修复bug也不是新增功能的代码变更
`perf`	无	性能优化
`test`	无	添加或修正测试用例
`build`	无	构建系统或外部依赖变更
`ci`	无	CI/CD配置变更
`chore`	无	日常任务、维护工作、工具调整
`revert`	视情况而定	回滚之前的提交

只有

feat

和

fix

会对SemVer产生隐含影响。其他所有类型除非伴随破坏性变更标记，否则不会自动触发版本号升级。

Breaking Changes

破坏性变更

Two equivalent methods exist — use either or both:

Method 1 —
!
after type/scope:

feat(api)!: remove deprecated endpoint /v1/users

Method 2 —
BREAKING CHANGE
footer:

feat(api): remove deprecated endpoint /v1/users

BREAKING CHANGE: /v1/users is removed. Migrate to /v2/users.

Both combined (maximum visibility):

feat(api)!: remove deprecated endpoint /v1/users

BREAKING CHANGE: /v1/users is removed. Migrate to /v2/users.

A breaking change MUST use uppercase

BREAKING CHANGE

in the footer.

BREAKING-CHANGE

is a valid synonym.

有两种等效的标记方式——可任选其一或同时使用：

方式1 — 在type/scope后添加
!
：

feat(api)!: 移除已废弃的接口 /v1/users

方式2 — 新增
BREAKING CHANGE
footer：

feat(api): 移除已废弃的接口 /v1/users

BREAKING CHANGE: /v1/users接口已移除，请迁移至/v2/users。

同时使用两种方式（可见性最大化）：

feat(api)!: 移除已废弃的接口 /v1/users

BREAKING CHANGE: /v1/users接口已移除，请迁移至/v2/users。

破坏性变更的footer必须使用大写的

BREAKING CHANGE

。

BREAKING-CHANGE

是有效的同义词。

Workflow: Writing a Commit Message

编写提交信息的工作流程

Step 1 — Identify the primary intent: Determine whether the change adds a feature, fixes a bug, or is maintenance/housekeeping.

Step 2 — Choose the type: Pick the single most appropriate type from the table above. If a change spans multiple types, split it into separate commits.

Step 3 — Determine scope (optional): Choose a short noun representing the affected module, component, or area:

auth

parser

api

ui

deps

Step 4 — Detect breaking changes: Ask: "Does this change require consumers to update their code?" If yes, apply

and/or add a

BREAKING CHANGE

footer.

Step 5 — Write the description:

Use imperative mood: "add", "fix", "remove", "update" — not "added", "fixes", "removing"
Keep under 72 characters
Do not capitalize the first letter (consistency convention)
Do not end with a period

Step 6 — Add body if needed: Explain the why, not the what. Wrap at 72 characters. Separate from description with one blank line.

Step 7 — Add footers if needed: Reference issues, reviewers, or co-authors using

Token: value

format.

步骤1 — 确定核心意图： 判断变更是新增功能、修复bug，还是维护/整理类工作。

步骤2 — 选择类型： 从上述表格中挑选最贴合的单一类型。如果变更涉及多个类型，应拆分为多个独立提交。

步骤3 — 确定scope（可选）： 选择一个简短的名词代表受影响的模块、组件或区域：

auth

、

parser

、

api

、

ui

、

deps

等。

步骤4 — 检测破坏性变更： 自问：「此变更是否要求使用者更新其代码？」如果是，则添加

和/或

BREAKING CHANGE

footer。

步骤5 — 编写description：

使用祈使语气：用「add」「fix」「remove」「update」，而非「added」「fixes」「removing」
长度控制在72字符以内
首字母无需大写（遵循一致性约定）
结尾无需加句号

步骤6 — 按需添加body： 解释「原因」而非「内容」。每行不超过72字符。与description之间空一行。

步骤7 — 按需添加footer： 使用

Token: value

格式引用问题、评审人或共同作者。

Quick Examples

快速示例

feat: add OAuth2 login support

fix(auth): prevent session expiry on page refresh

docs: update API reference for /v2/search endpoint

refactor(parser): extract token validation into separate module

perf(db): add index on users.email for faster lookup

chore(deps): bump lodash from 4.17.20 to 4.17.21

feat!: drop support for Node.js 14

BREAKING CHANGE: minimum required Node.js version is now 18.

fix: prevent racing of requests

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

Reviewed-by: Alice
Refs: #123

feat: 新增OAuth2登录支持

fix(auth): 修复页面刷新时会话过期的问题

docs: 更新/v2/search接口的API参考文档

refactor(parser): 将令牌验证逻辑提取到独立模块

perf(db): 为users.email字段添加索引以加快查询速度

chore(deps): 将lodash版本从4.17.20升级至4.17.21

feat!: 移除对Node.js 14的支持

BREAKING CHANGE: 现在最低要求的Node.js版本为18。

fix: 防止请求竞态问题

引入请求ID并记录最新请求的引用。
驳回除最新请求之外的所有响应。

Reviewed-by: Alice
Refs: #123

Footer Conventions

Footer约定

Footers follow git trailer format —

Token: value

Token #value

Footer	Purpose
`BREAKING CHANGE: <desc>`	Documents a breaking API change
`Refs: #123`	Links to a related issue or PR
`Reviewed-by: Name`	Credits a code reviewer
`Co-authored-by: Name <email>`	Credits a co-author
`Fixes: #456`	Closes an issue on merge

Token names use hyphens instead of spaces (e.g.

Co-authored-by

BREAKING CHANGE

is the sole exception — it may contain a space.

Footer遵循git尾部格式——

Token: value

或

Token #value

：

Footer	用途
`BREAKING CHANGE: <desc>`	记录破坏性API变更
`Refs: #123`	关联相关问题或PR
`Reviewed-by: Name`	标注代码评审人
`Co-authored-by: Name <email>`	标注共同作者
`Fixes: #456`	合并后自动关闭对应问题

Token名称使用连字符而非空格（例如

Co-authored-by

）。

BREAKING CHANGE

是唯一例外——它可以包含空格。

Scope Guidelines

Scope指南

Scopes are project-specific nouns. Common patterns:

By module:
```
feat(auth):
```
,
```
fix(parser):
```
,
```
test(api):
```
By layer:
```
refactor(db):
```
,
```
perf(cache):
```
,
```
build(docker):
```
By UI area:
```
feat(login):
```
,
```
style(nav):
```
,
```
fix(modal):
```

Keep scopes consistent within a project. Define the allowed scope list in a contributing guide or commitlint config if the team is large.

Scope是项目特定的名词，常见模式：

按模块划分：
```
feat(auth):
```
、
```
fix(parser):
```
、
```
test(api):
```
按层级划分：
```
refactor(db):
```
、
```
perf(cache):
```
、
```
build(docker):
```
按UI区域划分：
```
feat(login):
```
、
```
style(nav):
```
、
```
fix(modal):
```

在项目内部保持Scope的一致性。如果团队规模较大，可在贡献指南或commitlint配置中定义允许的Scope列表。

SemVer Mapping

SemVer映射关系

Commit type	Resulting version bump
`fix`	PATCH (0.0.x)
`feat`	MINOR (0.x.0)
Any type with `BREAKING CHANGE` or `!`	MAJOR (x.0.0)

Tools such as

semantic-release

and

standard-version

parse commit history to automate this version bump.

提交类型	对应的版本升级
`fix`	PATCH（0.0.x）
`feat`	MINOR（0.x.0）
任何带有 `BREAKING CHANGE` 或 `!` 的类型	MAJOR（x.0.0）

semantic-release

和

standard-version

等工具可解析提交历史，自动完成版本升级。

Common Mistakes to Avoid

需避免的常见错误

Vague descriptions:

fix: bug

→

fix(auth): handle null token in session middleware

Wrong type: using
```
chore
```
for a bug fix; use
```
fix
```
Multiple intents in one commit: one commit = one logical change
Missing blank line before body or footers: parsers rely on the blank line separator
Lowercase
breaking change
in footer: MUST be
```
BREAKING CHANGE
```
(uppercase)
Missing space after colon:
```
feat:description
```
is invalid; must be
```
feat: description
```

模糊的描述：

fix: bug

→ 应改为

fix(auth): 处理会话中间件中的空令牌问题

错误的类型：用
```
chore
```
标记bug修复；应使用
```
fix
```
单提交多意图：一个提交应对应一个逻辑变更
body或footer前缺少空行：解析器依赖空行作为分隔符
footer中使用小写的
breaking change
：必须使用大写的
```
BREAKING CHANGE
```
冒号后缺少空格：
```
feat:description
```
无效，必须写成
```
feat: description
```

Additional Resources

额外资源

Reference Files

参考文档

references/commit-types.md
— Detailed guidance and examples for every commit type, including edge cases and when types overlap
references/advanced-patterns.md
— Breaking changes, multi-footer commits, revert commits, monorepo scopes, and tooling integration (commitlint, semantic-release)

references/commit-types.md
— 每种提交类型的详细指南和示例，包括边缘情况和类型重叠场景的处理
references/advanced-patterns.md
— 破坏性变更、多footer提交、回滚提交、单体仓库Scope、工具集成（commitlint、semantic-release）等进阶内容