write-conventional-commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Conventional Commit

编写Conventional Commit提交信息

Generate and apply Conventional Commits that follow the 1.0.0 specification.

生成并遵循1.0.0规范的Conventional Commits提交信息。

Workflow

工作流程

Step 1: Inspect commit scope

步骤1：检查提交范围

Run from repository root:

bash

git status --short
git diff --staged --name-only
git diff --name-only

Use staged changes when available. If nothing is staged and the user asked to commit now, stage intentionally relevant files first and state what was staged.

从仓库根目录运行：

bash

git status --short
git diff --staged --name-only
git diff --name-only

当存在暂存变更时使用暂存内容。如果没有任何内容被暂存且用户要求立即提交，请先暂存相关文件，并说明暂存了哪些内容。

Step 2: Classify intent into commit type

步骤2：将意图分类为提交类型

Pick the best type from change intent, not from file extension.

Common types:

```
feat
```
: add a user-facing feature
```
fix
```
: fix a bug
```
refactor
```
: code change without new feature or bug fix
```
perf
```
: improve performance
```
docs
```
: documentation only
```
test
```
: add/update tests
```
build
```
: build/dependency tooling
```
ci
```
: CI/CD configuration
```
chore
```
: maintenance that does not fit above
```
revert
```
: revert a previous commit

If uncertain between

feat

and

fix

, prefer:

```
fix
```
when correcting broken behavior
```
feat
```
when adding new behavior

根据变更意图选择最合适的类型，而非根据文件扩展名。

常见类型：

```
feat
```
: 添加面向用户的功能
```
fix
```
: 修复bug
```
refactor
```
: 代码变更，既不添加新功能也不修复bug
```
perf
```
: 提升性能
```
docs
```
: 仅涉及文档变更
```
test
```
: 添加/更新测试
```
build
```
: 构建/依赖工具相关变更
```
ci
```
: CI/CD配置变更
```
chore
```
: 不属于上述类别的维护工作
```
revert
```
: 回滚之前的提交

如果在

feat

和

fix

之间不确定，优先选择：

```
fix
```
用于修正已损坏的行为
```
feat
```
用于添加新行为

Step 3: Choose optional scope

步骤3：选择可选的范围

Scope is optional and should be short and stable.

Prefer one of:

top-level package/app (
```
api
```
,
```
billing
```
,
```
auth
```
)
subsystem (
```
migrations
```
,
```
deps
```
,
```
release
```
)
user-visible surface (
```
checkout
```
,
```
search
```
)

Avoid broad scopes like

misc

范围是可选的，应简短且稳定。

优先选择以下类型之一：

顶级包/应用（
```
api
```
,
```
billing
```
,
```
auth
```
）
子系统（
```
migrations
```
,
```
deps
```
,
```
release
```
）
用户可见界面（
```
checkout
```
,
```
search
```
）

避免使用

misc

这类宽泛的范围。

Step 4: Detect breaking changes

步骤4：检测破坏性变更

Mark breaking changes when diff indicates incompatible API/contract behavior.

Signals include:

removed/renamed public endpoints, fields, events, CLI flags
required inputs changed incompatibly
output schema changed incompatibly

When breaking:

Add
```
!
```
after type or type+scope (
```
feat!:
```
or
```
feat(api)!:
```
)

Add footer:

BREAKING CHANGE: <what changed and how to migrate>

Use both when possible for clarity.

当差异显示存在不兼容的API/契约行为时，标记破坏性变更。

信号包括：

移除/重命名公开端点、字段、事件、CLI标志
必填输入发生不兼容变更
输出 schema 发生不兼容变更

当存在破坏性变更时：

在类型或类型+范围后添加
```
!
```
（如
```
feat!:
```
或
```
feat(api)!:
```
）

添加脚注：

BREAKING CHANGE: <变更内容及迁移方式>

尽可能同时使用两者以确保清晰。

Step 5: Compose message in spec format

步骤5：按照规范格式撰写信息

Use this structure exactly:

text

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

[optional body]

[optional footer(s)]

Formatting rules:

Header type must be lowercase noun.
Put a colon and single space after header prefix.
Keep description concise and specific.
Put one blank line between header and body.
Put one blank line between body and footers.
Footer tokens follow git trailer style (
```
Token: value
```
), except references may use
```
Token #value
```
.
Use
```
BREAKING CHANGE:
```
as the canonical breaking footer token.

严格使用以下结构：

text

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

[optional body]

[optional footer(s)]

格式规则：

标题类型必须是小写名词
标题前缀后添加冒号和单个空格
描述应简洁具体
标题和正文之间留一个空行
正文和脚注之间留一个空行
脚注标记遵循Git尾部格式（
```
Token: value
```
），但引用可使用
```
Token #value
```
使用
```
BREAKING CHANGE:
```
作为标准的破坏性变更脚注标记

Step 6: Create commit (when requested)

步骤6：创建提交（当用户要求时）

If user wants the commit executed, run non-interactively:

bash

git commit -m "<header>" -m "<body>" -m "<footer1>" -m "<footer2>"

Only include

-m

blocks that are needed.

For multiline body/footer with precise formatting, use:

bash

git commit -F /tmp/commit-msg.txt

Then report:

final commit header
commit hash
whether breaking change was marked

如果用户要求执行提交，以非交互方式运行：

bash

git commit -m "<header>" -m "<body>" -m "<footer1>" -m "<footer2>"

仅包含需要的

-m

参数块。

对于需要精确格式的多行正文/脚注，使用：

bash

git commit -F /tmp/commit-msg.txt

然后报告：

最终提交标题
提交哈希
是否标记了破坏性变更

Quality checks

质量检查

Before finalizing, verify:

Header matches
```
<type>[scope][!]: description
```
Type reflects intent correctly
Scope is helpful or omitted
Breaking changes are explicitly marked when applicable
Body explains why when context is not obvious
Footers are valid trailers and references are accurate

在最终确定前，验证：

标题符合
```
<type>[scope][!]: description
```
格式
类型准确反映变更意图
范围有帮助或已省略
当存在破坏性变更时已明确标记
当上下文不明确时，正文解释了变更原因
脚注是有效的尾部格式，引用准确

Output behavior

输出行为

When user asks only for message suggestions, provide 1 recommended message and up to 2 alternatives.

When user asks to commit directly, proceed with staging/commit commands and then return commit result.

当用户仅要求提供提交信息建议时，提供1条推荐信息和最多2条备选信息。

当用户要求直接提交时，执行暂存/提交命令，然后返回提交结果。

Reference

参考

Read references/conventional-commits-1.0.0.md for the normative checklist and examples.

阅读references/conventional-commits-1.0.0.md获取规范性检查清单和示例。