conventional-commits

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Conventional Commits (v1.0.0)

Conventional Commits（v1.0.0）

Use the Conventional Commits spec to produce consistent commit messages that are easy to parse for changelogs and semantic versioning.

使用Conventional Commits规范来生成一致的提交信息，便于解析以生成变更日志和实现语义化版本控制。

Commit message format (canonical)

提交信息格式（标准）

text

<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]

Rules:

Separate header, body, footers with a blank line.
Keep the header on one line.
Put
```
!
```
immediately before
```
:
```
to mark a breaking change (e.g.
```
feat!: ...
```
,
```
refactor(api)!: ...
```
).

text

<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]

规则：

用空行分隔标题、正文、页脚。
标题保持在一行内。
在
```
:
```
前添加
```
!
```
标记破坏性变更（例如：
```
feat!: ...
```
，
```
refactor(api)!: ...
```
）。

Choose a type

选择类型

The spec allows any type, but these are common and widely supported by tooling:

```
feat
```
: introduce a new feature (user-facing)
```
fix
```
: bug fix (user-facing)
```
docs
```
: documentation-only changes
```
refactor
```
: refactor that neither fixes a bug nor adds a feature
```
perf
```
: performance improvement
```
test
```
: add or adjust tests
```
build
```
: build system/dependencies
```
ci
```
: CI configuration/scripts
```
chore
```
: maintenance tasks
```
style
```
: formatting (whitespace, missing semicolons, etc.)
```
revert
```
: revert a previous commit

Default choice when unsure:

If users see new behavior →
```
feat
```
If users see corrected behavior →
```
fix
```
Otherwise →
```
chore
```
or a more specific maintenance type (
```
refactor
```
,
```
build
```
,
```
ci
```
)

规范允许使用任何类型，但以下类型是常见且被工具广泛支持的：

```
feat
```
: 引入新功能（面向用户）
```
fix
```
: 修复Bug（面向用户）
```
docs
```
: 仅修改文档
```
refactor
```
: 既不修复Bug也不添加功能的重构
```
perf
```
: 性能优化
```
test
```
: 添加或调整测试
```
build
```
: 构建系统/依赖项变更
```
ci
```
: CI配置/脚本变更
```
chore
```
: 维护任务
```
style
```
: 格式调整（空格、缺失分号等）
```
revert
```
: 撤销之前的提交

不确定时的默认选择：

如果用户看到新行为 →
```
feat
```
如果用户看到修正后的行为 →
```
fix
```
其他情况 →
```
chore
```
或更具体的维护类型（
```
refactor
```
、
```
build
```
、
```
ci
```
）

Optional scope

可选范围

Use scope to clarify the area impacted.

Format:

text

type(scope): description

Guidelines:

Use a short noun:
```
api
```
,
```
auth
```
,
```
ui
```
,
```
db
```
,
```
cli
```
,
```
deps
```
,
```
docs
```
.
Use repo/module/package name when working in a monorepo.
If scope adds no clarity, omit it.

使用范围来明确受影响的区域。

格式：

text

type(scope): description

指南：

使用简短的名词：
```
api
```
、
```
auth
```
、
```
ui
```
、
```
db
```
、
```
cli
```
、
```
deps
```
、
```
docs
```
。
在单体仓库中工作时，使用仓库/模块/包名称。
如果范围不能增加清晰度，则省略。

Description (subject)

描述（主题）

Write the description as a short summary of what the change does.

Guidelines:

Use imperative mood: “add”, “fix”, “remove”, “update”.
Avoid ending punctuation.
Be specific; avoid “stuff”, “changes”, “update things”.

Examples:

text

feat(auth): add passwordless login
fix(api): handle empty pagination cursor
chore(deps): bump react to 18.3.0

将描述写为变更内容的简短摘要。

指南：

使用祈使语气：“add”、“fix”、“remove”、“update”。
避免结尾使用标点符号。
具体明确；避免使用“stuff”、“changes”、“update things”这类模糊表述。

示例：

text

feat(auth): add passwordless login
fix(api): handle empty pagination cursor
chore(deps): bump react to 18.3.0

Body (optional)

正文（可选）

Use the body to explain motivation, constraints, or high-level implementation notes.

Guidelines:

Prefer complete sentences.
If helpful, include:
- why the change was needed
- what approach was chosen
- notable trade-offs

Example:

text

refactor(parser): simplify tokenization

Replace the regex pipeline with a small state machine to reduce backtracking.

使用正文来解释变更动机、约束条件或高层实现说明。

指南：

优先使用完整句子。
如果有帮助，可包含：
- 为什么需要此变更
- 选择了哪种实现方案
- 值得注意的权衡

示例：

text

refactor(parser): simplify tokenization

Replace the regex pipeline with a small state machine to reduce backtracking.

Footers (optional)

页脚（可选）

Footers are key/value-like lines at the end. Use them for:

breaking change details
issue references
metadata used by tooling

Examples:

text

Refs: #123
Closes: #456
Co-authored-by: Name <email@example.com>

页脚是末尾的键值对格式行。可用于：

破坏性变更的详细信息
关联的问题ID
工具使用的元数据

示例：

text

Refs: #123
Closes: #456
Co-authored-by: Name <email@example.com>

Breaking changes

破坏性变更

Mark breaking changes in one (or both) of these ways:

Add
```
!
```
in the header:

text

feat(api)!: remove deprecated v1 endpoints

Add a
```
BREAKING CHANGE:
```
footer (recommended when you need an explanation):

text

feat(api): remove deprecated v1 endpoints

BREAKING CHANGE: /v1/* endpoints are removed; migrate to /v2/*.

通过以下一种（或两种）方式标记破坏性变更：

在标题中添加
```
!
```
：

text

feat(api)!: remove deprecated v1 endpoints

添加
```
BREAKING CHANGE:
```
页脚（当需要解释时推荐使用）：

text

feat(api): remove deprecated v1 endpoints

BREAKING CHANGE: /v1/* endpoints are removed; migrate to /v2/*.

Reverts

撤销操作

Use the

revert

type when undoing a previous change.

Example:

text

revert: feat(auth): add passwordless login

This reverts commit 1a2b3c4.

当需要撤销之前的变更时，使用

revert

类型。

示例：

text

revert: feat(auth): add passwordless login

This reverts commit 1a2b3c4.

Semantic versioning mapping (typical)

语义化版本控制映射（常规）

Common mapping for automated version bumps:

```
fix
```
→ patch
```
feat
```
→ minor
any breaking change (
```
!
```
or
```
BREAKING CHANGE:
```
) → major

自动版本升级的常见映射：

```
fix
```
→ 补丁版本（patch）
```
feat
```
→ 次版本（minor）
任何破坏性变更（
```
!
```
或
```
BREAKING CHANGE:
```
）→ 主版本（major）

When asked to “write a commit message”

当被要求“编写提交信息”时

Collect missing inputs quickly:

What changed? (1–2 sentences)
Scope/module? (optional)
User-facing? (feature vs fix vs chore)
Breaking? (yes/no; migration note if yes)
Any issue IDs to reference?

Then produce:

A conventional header
Optional body (only if it adds clarity)
Optional footers (
```
Refs:
```
,
```
Closes:
```
,
```
BREAKING CHANGE:
```
)

快速收集缺失的信息：

变更了什么？（1-2句话）
范围/模块？（可选）
是否面向用户？（功能/修复/维护）
是否是破坏性变更？（是/否；如果是，提供迁移说明）
是否有需要关联的问题ID？

然后生成：

符合规范的标题
可选的正文（仅当能增加清晰度时添加）
可选的页脚（
```
Refs:
```
、
```
Closes:
```
、
```
BREAKING CHANGE:
```
）

Ready-to-use templates

即用型模板

Minimal:

text

<type>: <description>

With scope:

text

<type>(<scope>): <description>

Breaking change with explanation:

text

<type>(<scope>): <description>

BREAKING CHANGE: <what breaks and how to migrate>

极简版：

text

<type>: <description>

带范围：

text

<type>(<scope>): <description>

带说明的破坏性变更：

text

<type>(<scope>): <description>

BREAKING CHANGE: <what breaks and how to migrate>