Back to Details

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

常见类型

TypePurposeSemVer
feat
New featureMINOR
fix
Bug fixPATCH
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
修复BugPATCH
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

必须遵守

  1. Commits MUST be prefixed with a type (
    feat
    , 
    fix
    , etc.)
  2. Type MUST be followed by colon and space
  3. Description MUST immediately follow the colon and space
  4. feat
    MUST be used for new features
  5. fix
    MUST be used for bug fixes
  6. Breaking changes MUST be indicated by 
    !
    before 
    :
    OR 
    BREAKING CHANGE:
    footer
  7. BREAKING CHANGE
    MUST be uppercase
  8. Footer token MUST use 
    -
    instead of spaces (e.g., 
    Reviewed-by
    )
  1. 提交消息必须以类型前缀开头（如
    feat
    、
    fix
    等）
  2. 类型后必须跟冒号和空格
  3. 描述必须紧跟在冒号和空格之后
  4. 新增功能必须使用
    feat
    类型
  5. Bug修复必须使用
    fix
    类型
  6. 破坏性变更必须通过
    :
    前的
    !
    或
    BREAKING CHANGE:
    页脚来标识
  7. BREAKING CHANGE
    必须大写
  8. 页脚标识必须使用
    -
    代替空格（如
    Reviewed-by
    ）

MAY

可选操作

  1. Scope MAY be provided after type: 
    feat(parser):
  2. Body MAY be provided after description (blank line between)
  3. Footer MAY be provided after body (blank line between)
  4. Types other than 
    feat
    and 
    fix
    MAY be used
  5. !
    MAY be used with 
    BREAKING CHANGE:
    footer
  1. 类型后可以添加作用域：
    feat(parser):
  2. 描述后可以添加正文（与描述之间空一行）
  3. 正文后可以添加页脚（与正文之间空一行）
  4. 可以使用
    feat
    和
    fix
    之外的其他类型
  5. 可以同时使用
    !
    和
    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 TypeSemVer BumpVersion Change
fix:
PATCH1.0.0 → 1.0.1
feat:
MINOR1.0.0 → 1.1.0
BREAKING CHANGE
or 
!
MAJOR1.0.0 → 2.0.0
Breaking changes override type — 
fix!:
results in MAJOR bump.
提交类型SemVer 版本变更版本示例
fix:
PATCH1.0.0 → 1.0.1
feat:
MINOR1.0.0 → 1.1.0
BREAKING CHANGE
或 
!
MAJOR1.0.0 → 2.0.0
破坏性变更会覆盖类型规则 —— 
fix!:
会触发MAJOR版本变更。

Changelog Integration

变更日志集成

Conventional Commits map directly to changelog entries:
Commit TypeChangelog 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 fixesSecurity
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

工具

ToolPurpose
commitlintLint commit messages
commitizenInteractive commit helper
conventional-changelogGenerate changelogs
semantic-releaseAutomated releases
release-pleaseGitHub release automation
工具链接用途
commitlint校验提交消息格式
commitizen交互式提交消息辅助工具
conventional-changelog生成变更日志
semantic-release自动化版本发布
release-pleaseGitHub版本发布自动化工具

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:
  1. Check all changed files using 
    git status
    or 
    git diff --name-only
  2. Review actual changes using 
    git diff
    (staged and unstaged)
  3. Analyze ALL modifications — not just the files mentioned in conversation
  4. Base proposals on complete changeset — include all affected files, not partial list
强制要求：在提议分支名称、提交消息或PR描述之前，Agent必须：
  1. 检查所有变更文件：使用
    git status
    或
    git diff --name-only
  2. 查看实际变更内容：使用
    git diff
    （暂存和未暂存的变更）
  3. 分析所有修改 —— 不仅限于对话中提到的文件
  4. 基于完整变更集提出建议 —— 包含所有受影响的文件，而非部分列表

Workflow Steps

工作流步骤

bash
undefined
bash
undefined

Step 1: Get list of all changed files

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

git status --short
git status --short

Step 2: Review actual changes (for unstaged)

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

git diff
git diff

Step 3: Review staged changes

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

git diff --staged
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:
  1. Branch name options (3 variants using conventional prefixes)
  2. Commit message variants (short/medium/detailed)
  3. PR description (summarized, not duplicating full changelog)
All proposals MUST be based on the actual 
git diff
output, not assumptions.
当用户请求提交消息时，需提供：
  1. 分支名称选项（3个使用规范前缀的变体）
  2. 提交消息选项（简短/中等/详细版本）
  3. PR描述（总结性内容，无需重复完整变更日志）
所有建议必须基于实际的
git diff
输出，而非假设。

Links

链接

Templates

模板

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