commits

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Conventional Commits

Conventional Commits 规范

Specification for structured commit messages that enable automated changelog generation and semantic versioning.

这是一种结构化提交消息的规范，可实现自动生成变更日志和语义化版本控制。

Quick Reference

快速参考

Format

格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

<type>[可选 scope]: <描述>

[可选正文]

[可选页脚]

Common Types

常见类型

Type	Purpose	SemVer
`feat`	New feature	MINOR
`fix`	Bug fix	PATCH
`docs`	Documentation only	-
`style`	Formatting, no code change	-
`refactor`	Code change, no feature/fix	-
`perf`	Performance improvement	-
`test`	Adding/fixing tests	-
`build`	Build system, dependencies	-
`ci`	CI configuration	-
`chore`	Maintenance tasks	-
`revert`	Revert previous commit	-

类型	用途	SemVer
`feat`	新增功能	MINOR
`fix`	修复Bug	PATCH
`docs`	仅修改文档	-
`style`	代码格式调整，无代码逻辑变更	-
`refactor`	代码重构，无新增功能或Bug修复	-
`perf`	性能优化	-
`test`	添加或修复测试用例	-
`build`	构建系统或依赖项修改	-
`ci`	CI配置修改	-
`chore`	维护任务	-
`revert`	回滚之前的提交	-

Breaking Changes

破坏性变更

feat!: send email when product shipped

feat(api)!: change response format

chore!: drop support for Node 6

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

feat!: 产品发货时发送邮件

feat(api)!: 修改响应格式

chore!: 停止支持 Node 6

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

Examples

示例

Simple Commits

简单提交

feat: add user authentication
fix: resolve memory leak in cache
docs: update API documentation
style: format code with prettier
refactor: extract validation logic
perf: optimize database queries
test: add unit tests for auth module
build: upgrade webpack to v5
ci: add GitHub Actions workflow
chore: update dependencies

feat: 添加用户认证功能
fix: 修复缓存中的内存泄漏问题
docs: 更新API文档
style: 使用prettier格式化代码
refactor: 提取验证逻辑
perf: 优化数据库查询
test: 为认证模块添加单元测试
build: 将webpack升级到v5版本
ci: 添加GitHub Actions工作流
chore: 更新依赖项

With Scope

带作用域的提交

feat(auth): add OAuth2 support
fix(parser): handle empty arrays
docs(readme): add installation guide
refactor(api): simplify error handling

feat(auth): 添加OAuth2支持
fix(parser): 处理空数组情况
docs(readme): 添加安装指南
refactor(api): 简化错误处理逻辑

With Body

带正文的提交

fix: prevent request racing

Introduce a request id and 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: 防止请求竞态问题

引入请求ID并关联最新请求。
忽略非最新请求的响应。
移除之前用于缓解竞态问题的超时机制，该机制现已过时。

With Footer

带页脚的提交

fix: correct minor typos in code

Reviewed-by: John Doe
Refs: #123

fix: 修正代码中的小拼写错误

Reviewed-by: John Doe
Refs: #123

Breaking Change in Footer

页脚中声明破坏性变更

feat: allow config object to extend other configs

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

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

BREAKING CHANGE: 配置文件中的`extends`键现在用于继承其他配置文件。

Breaking Change with ! and Footer

用!和页脚声明破坏性变更

chore!: drop support for Node 6

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

chore!: 停止支持Node 6

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

Revert Commit

回滚提交

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

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

Refs: 676104e, a215868

Specification Rules

规范规则

MUST

必须遵守

Commits MUST be prefixed with a type (
```
feat
```
,
```
fix
```
, etc.)
Type MUST be followed by colon and space
Description MUST immediately follow the colon and space
```
feat
```
MUST be used for new features
```
fix
```
MUST be used for bug fixes
Breaking changes MUST be indicated by
```
!
```
before
```
:
```
OR
```
BREAKING CHANGE:
```
footer
```
BREAKING CHANGE
```
MUST be uppercase
Footer token MUST use
```
-
```
instead of spaces (e.g.,
```
Reviewed-by
```
)

提交消息必须以类型前缀开头（如
```
feat
```
、
```
fix
```
等）
类型后必须跟冒号和空格
描述必须紧跟在冒号和空格之后
新增功能必须使用
```
feat
```
类型
Bug修复必须使用
```
fix
```
类型
破坏性变更必须通过
```
:
```
前的
```
!
```
或
```
BREAKING CHANGE:
```
页脚来标识
```
BREAKING CHANGE
```
必须大写
页脚标识必须使用
```
-
```
代替空格（如
```
Reviewed-by
```
）

MAY

可选操作

Scope MAY be provided after type:
```
feat(parser):
```
Body MAY be provided after description (blank line between)
Footer MAY be provided after body (blank line between)
Types other than
```
feat
```
and
```
fix
```
MAY be used
```
!
```
MAY be used with
```
BREAKING CHANGE:
```
footer

类型后可以添加作用域：
```
feat(parser):
```
描述后可以添加正文（与描述之间空一行）
正文后可以添加页脚（与正文之间空一行）
可以使用
```
feat
```
和
```
fix
```
之外的其他类型
可以同时使用
```
!
```
和
```
BREAKING CHANGE:
```
页脚

Case Sensitivity

大小写规则

Types: case-insensitive (lowercase recommended for consistency)
```
BREAKING CHANGE
```
: MUST be uppercase
```
BREAKING-CHANGE
```
: synonym for
```
BREAKING CHANGE
```

类型：不区分大小写（建议使用小写以保持一致性）
```
BREAKING CHANGE
```
：必须大写
```
BREAKING-CHANGE
```
：是
```
BREAKING CHANGE
```
的同义词

SemVer Mapping

语义化版本映射

Commit Type	SemVer Bump	Version Change
`fix:`	PATCH	1.0.0 → 1.0.1
`feat:`	MINOR	1.0.0 → 1.1.0
`BREAKING CHANGE` or `!`	MAJOR	1.0.0 → 2.0.0

Breaking changes override type —

fix!:

results in MAJOR bump.

提交类型	SemVer 版本变更	版本示例
`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

破坏性变更会覆盖类型规则 ——

fix!:

会触发MAJOR版本变更。

Changelog Integration

变更日志集成

Conventional Commits map directly to changelog entries:

Commit Type	Changelog Section
`feat`	Added
`fix`	Fixed
`perf`	Changed
`refactor`	Changed
`docs`	(usually omitted or Changed)
`BREAKING CHANGE`	Highlight in Changed/Removed
`revert`	Removed or Fixed
Security fixes	Security

Conventional Commits 可直接映射到变更日志条目：

提交类型	变更日志章节
`feat`	新增功能
`fix`	Bug修复
`perf`	功能变更
`refactor`	功能变更
`docs`	（通常省略或归入功能变更）
`BREAKING CHANGE`	在功能变更/移除功能中高亮显示
`revert`	移除功能或Bug修复
安全修复	安全更新

Automated Changelog Generation

自动生成变更日志

Tools like

conventional-changelog

semantic-release

, or

release-please

can:

Parse commit messages
Generate CHANGELOG.md entries
Determine next version number
Create releases automatically

See changelog skill for CHANGELOG.md format.

conventional-changelog

、

semantic-release

或

release-please

等工具可以：

解析提交消息
生成CHANGELOG.md条目
确定下一个版本号
自动创建版本发布

有关CHANGELOG.md格式，请查看变更日志技能。

Common Patterns

常见模式

Feature Development

功能开发流程

bash

git commit -m "feat(users): add profile page"
git commit -m "feat(users): add avatar upload"
git commit -m "test(users): add profile page tests"
git commit -m "docs(users): document profile API"

bash

git commit -m "feat(users): 添加个人资料页面"
git commit -m "feat(users): 添加头像上传功能"
git commit -m "test(users): 添加个人资料页面测试"
git commit -m "docs(users): 编写个人资料API文档"

Bug Fix with Reference

关联引用的Bug修复

bash

git commit -m "fix(auth): resolve session timeout (#142)"

bash

git commit -m "fix(auth): 解决会话超时问题 (#142)"

Breaking Change Flow

破坏性变更流程

bash

undefined

bash

undefined

Deprecate first

先标记废弃

git commit -m "feat(api): add v2 endpoint

DEPRECATED: /api/v1/users will be removed in next major version"

git commit -m "feat(api): 添加v2版本接口

DEPRECATED: /api/v1/users 接口将在下一个主版本中移除"

Later, remove

后续移除

git commit -m "feat(api)!: remove v1 endpoints

BREAKING CHANGE: /api/v1/* endpoints have been removed. Use /api/v2/* instead."

undefined

git commit -m "feat(api)!: 移除v1版本接口

BREAKING CHANGE: /api/v1/* 接口已被移除。请使用 /api/v2/* 接口替代。"

undefined

FAQ

常见问题

What if commit fits multiple types?

如果一个提交符合多种类型怎么办？

Split into multiple commits when possible. This makes history more organized.

尽可能拆分为多个提交。这样会让提交历史更有条理。

What if I used wrong type?

如果我用错了类型怎么办？

Before merge:

git rebase -i

to edit history. After release: not critical — commit will be missed by automated tools.

合并前：使用

git rebase -i

编辑提交历史。发布后：影响不大 —— 该提交会被自动化工具忽略。

Do all contributors need to use this?

所有贡献者都必须使用这个规范吗？

No. Use squash merging and maintainers can write proper message for the merge.

不需要。可以使用 squash 合并，维护者可以为合并提交编写符合规范的消息。

How to handle reverts?

如何处理回滚提交？

revert: <original commit subject>

Refs: <commit SHA>

revert: <原提交主题>

Refs: <提交SHA值>

Git Configuration

Git配置

Commit Template

提交模板

Set up git to use template:

bash

git config commit.template .gitmessage

See assets/commit-msg.template for template file.

配置Git使用提交模板：

bash

git config commit.template .gitmessage

模板文件可参考assets/commit-msg.template。

Pre-commit Validation

提交前校验

Use assets/validate-commit-msg.sh with git hooks or CI.

可将assets/validate-commit-msg.sh与Git钩子或CI集成，用于校验提交消息。

Tools

工具

Tool	Purpose
commitlint	Lint commit messages
commitizen	Interactive commit helper
conventional-changelog	Generate changelogs
semantic-release	Automated releases
release-please	GitHub release automation

工具链接	用途
commitlint	校验提交消息格式
commitizen	交互式提交消息辅助工具
conventional-changelog	生成变更日志
semantic-release	自动化版本发布
release-please	GitHub版本发布自动化工具

Critical Prohibitions

重要禁忌

Do not use vague messages ("fix stuff", "update", "wip")
Do not mix unrelated changes in single commit
Do not omit breaking change indicators
Do not use non-standard types without team agreement
Do not forget blank line between description and body

不要使用模糊的提交消息（如"修复问题"、"更新"、"进行中"）
不要在单个提交中混合无关变更
不要遗漏破坏性变更标识
不要未经团队同意使用非标准类型
不要忘记在描述和正文之间添加空行

Agent Workflow for Commit Messages

Agent 提交消息工作流

MANDATORY: Before proposing branch name, commit message, or PR description, the agent MUST:

Check all changed files using
```
git status
```
or
```
git diff --name-only
```
Review actual changes using
```
git diff
```
(staged and unstaged)
Analyze ALL modifications — not just the files mentioned in conversation
Base proposals on complete changeset — include all affected files, not partial list

强制要求：在提议分支名称、提交消息或PR描述之前，Agent必须：

检查所有变更文件：使用
```
git status
```
或
```
git diff --name-only
```
查看实际变更内容：使用
```
git diff
```
（暂存和未暂存的变更）
分析所有修改 —— 不仅限于对话中提到的文件
基于完整变更集提出建议 —— 包含所有受影响的文件，而非部分列表

Workflow Steps

工作流步骤

bash

undefined

bash

undefined

Step 1: Get list of all changed files

步骤1：获取所有变更文件列表

git status --short

Step 2: Review actual changes (for unstaged)

步骤2：查看未暂存的实际变更

git diff

Step 3: Review staged changes

步骤3：查看已暂存的变更

git diff --staged

Step 4: Use the complete changeset to propose:

步骤4：基于完整变更集提出以下内容：

- Branch name

- 分支名称选项

- Commit message

- 提交消息选项

- PR description

- PR描述

undefined

undefined

Output Format

输出格式

When user asks for commit message, provide:

Branch name options (3 variants using conventional prefixes)
Commit message variants (short/medium/detailed)
PR description (summarized, not duplicating full changelog)

All proposals MUST be based on the actual

git diff

output, not assumptions.

当用户请求提交消息时，需提供：

分支名称选项（3个使用规范前缀的变体）
提交消息选项（简短/中等/详细版本）
PR描述（总结性内容，无需重复完整变更日志）

所有建议必须基于实际的

git diff

输出，而非假设。

链接

Official specification: https://www.conventionalcommits.org/en/v1.0.0/
Semantic Versioning: https://semver.org/spec/v2.0.0.html
Related: changelog skill — CHANGELOG.md format

官方规范：https://www.conventionalcommits.org/en/v1.0.0/
语义化版本控制：https://semver.org/spec/v2.0.0.html
相关内容：变更日志技能 —— CHANGELOG.md格式说明

Templates

模板

commit-msg.template — Git commit message template
validate-commit-msg.sh — Validation script

commit-msg.template —— Git提交消息模板
validate-commit-msg.sh —— 校验脚本