Back to Details

conventional-commits

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Conventional Commits

Conventional Commits

This skill provides guidance for writing Git commits that follow the Conventional Commits specification (v1.0.0).
本技能为编写遵循Conventional Commits规范（v1.0.0）的Git提交信息提供指导。

Purpose

目的

Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. It provides an easy set of rules for creating an explicit commit history, which makes it easier to understand project changes and improve collaboration.
Conventional Commits是一种为提交信息赋予人类和机器可读含义的规范。它提供了一套简单的规则来创建清晰的提交历史，从而更易理解项目变更并提升协作效率。

When to Use This Skill

适用场景

Use this skill when:
  • Creating Git commits
  • Reviewing commit messages in PRs
  • Writing clear, structured commit messages
  • Collaborating on projects with multiple contributors
本技能适用于：
  • 创建Git提交时
  • 审查PR中的提交信息时
  • 编写清晰、结构化的提交信息时
  • 多贡献者协作的项目中

Commit Message Structure

提交信息结构

Basic Format

基础格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
<type>[可选 scope]: <描述>

[可选 正文]

[可选 页脚]

Examples

示例

feat: add user authentication
feat(api): add JWT token generation
fix: resolve memory leak in image processor
docs: update README with setup instructions
refactor(database): optimize user query performance
feat: add user authentication
feat(api): add JWT token generation
fix: resolve memory leak in image processor
docs: update README with setup instructions
refactor(database): optimize user query performance

Commit Types

提交类型

Primary Types

主要类型

feat - A new feature for the user
feat: add export to PDF functionality
feat(api): add webhook signature verification
fix - A bug fix for the user
fix: resolve login redirect loop
fix(api): handle null response from GitHub webhook
docs - Documentation only changes
docs: update API endpoint documentation
docs(readme): add troubleshooting section
style - Changes that don't affect code meaning (formatting, whitespace)
style: format code with StandardRB
style(css): update button padding
refactor - Code change that neither fixes a bug nor adds a feature
refactor: extract user validation to service object
refactor(models): simplify tenant scoping logic
perf - Performance improvements
perf: add database index for user lookups
perf(queries): reduce N+1 queries in artifacts index
test - Adding or updating tests
test: add specs for user authentication
test(integration): add webhook processing tests
chore - Changes to build process, dependencies, or maintenance
chore: update Rails to 7.2.0
chore(deps): bump sidekiq from 7.1.0 to 7.2.0
feat - 为用户新增功能
feat: add export to PDF functionality
feat(api): add webhook signature verification
fix - 修复用户侧的Bug
fix: resolve login redirect loop
fix(api): handle null response from GitHub webhook
docs - 仅修改文档
docs: update API endpoint documentation
docs(readme): add troubleshooting section
style - 不影响代码含义的变更（格式、空格等）
style: format code with StandardRB
style(css): update button padding
refactor - 既不是修复Bug也不是新增功能的代码变更
refactor: extract user validation to service object
refactor(models): simplify tenant scoping logic
perf - 性能优化
perf: add database index for user lookups
perf(queries): reduce N+1 queries in artifacts index
test - 添加或更新测试
test: add specs for user authentication
test(integration): add webhook processing tests
chore - 构建流程、依赖或维护类变更
chore: update Rails to 7.2.0
chore(deps): bump sidekiq from 7.1.0 to 7.2.0

Additional Types (Less Common)

其他类型（较不常用）

build - Changes to build system or dependencies
build: configure Docker for production
build(webpack): update asset compilation settings
ci - Changes to CI configuration
ci: add security scanning to GitHub Actions
ci(tests): run RSpec in parallel
revert - Reverts a previous commit
revert: revert "feat: add export feature"

This reverts commit abc123.
build - 构建系统或依赖变更
build: configure Docker for production
build(webpack): update asset compilation settings
ci - CI配置变更
ci: add security scanning to GitHub Actions
ci(tests): run RSpec in parallel
revert - 回滚之前的提交
revert: revert "feat: add export feature"

This reverts commit abc123.

Scope (Optional)

范围（可选）

Scope provides additional context about what part of the codebase changed:
feat(auth): add two-factor authentication
fix(api): handle rate limit errors
docs(contributing): update PR guidelines
refactor(services): extract common validation logic
Common scope examples:
  • auth
    - Authentication/authorization
  • api
    - API endpoints
  • ui
    - User interface components
  • database
    or 
    db
    - Database models/migrations
  • services
    - Service objects
  • jobs
    - Background jobs
  • tests
    - Test suite
  • deps
    - Dependencies
  • config
    - Configuration changes
  • docs
    - Documentation
Choose scopes that match your project's architecture and domain areas.
范围用于提供代码变更部分的额外上下文：
feat(auth): add two-factor authentication
fix(api): handle rate limit errors
docs(contributing): update PR guidelines
refactor(services): extract common validation logic
常见范围示例：
  • auth
    - 认证/授权
  • api
    - API端点
  • ui
    - 用户界面组件
  • database
    或 
    db
    - 数据库模型/迁移
  • services
    - 服务对象
  • jobs
    - 后台任务
  • tests
    - 测试套件
  • deps
    - 依赖
  • config
    - 配置变更
  • docs
    - 文档
请选择与项目架构和领域匹配的范围。

Description

描述

The description is a short summary of the code change:
Rules:
  • Use imperative, present tense: "add" not "added" or "adds"
  • Don't capitalize first letter
  • No period (.) at the end
  • Keep under 72 characters (ideally under 50)
Good descriptions:
add user profile page
fix memory leak in file upload
update email templates for notifications
remove deprecated API endpoint
Bad descriptions:
Added user profile page          # Past tense
Fix Memory Leak In File Upload   # Capitalized
Updated email templates.          # Period at end
Lots of changes to the codebase   # Vague
描述是代码变更的简短总结：
规则：
  • 使用祈使语气、现在时态：用“add”而非“added”或“adds”
  • 首字母不大写
  • 结尾不加句号（.）
  • 长度控制在72字符以内（理想情况下50字符以内）
优秀描述示例：
add user profile page
fix memory leak in file upload
update email templates for notifications
remove deprecated API endpoint
糟糕描述示例：
Added user profile page          # 过去时态
Fix Memory Leak In File Upload   # 首字母大写
Updated email templates.          # 结尾加句号
Lots of changes to the codebase   # 描述模糊

Body (Optional)

正文（可选）

The body provides additional context about the change:
When to include a body:
  • Complex changes needing explanation
  • Non-obvious design decisions
  • Breaking changes
  • Migration instructions
Format:
  • Separate from description with blank line
  • Use imperative mood like description
  • Wrap at 72 characters
  • Can include multiple paragraphs
Example:
feat(api): add webhook signature verification

Add HMAC-SHA256 signature verification for all incoming webhooks
to prevent unauthorized access and replay attacks.

The signature is validated using a secret key stored per
installation. Requests with invalid signatures are rejected
with a 401 response.
正文用于提供变更的额外上下文：
需要添加正文的场景：
  • 需要解释的复杂变更
  • 非显而易见的设计决策
  • 破坏性变更
  • 迁移说明
格式：
  • 与描述之间用空行分隔
  • 和描述一样使用祈使语气
  • 每行不超过72字符
  • 可包含多个段落
示例：
feat(api): add webhook signature verification

Add HMAC-SHA256 signature verification for all incoming webhooks
to prevent unauthorized access and replay attacks.

The signature is validated using a secret key stored per
installation. Requests with invalid signatures are rejected
with a 401 response.

Footer (Optional)

页脚（可选）

Footers provide metadata about the commit:
页脚用于提供提交的元数据：

Breaking Changes

破坏性变更

Use 
BREAKING CHANGE:
footer for incompatible API changes:
feat(api): change authentication endpoint

BREAKING CHANGE: The /auth endpoint now requires a client_id parameter.
Update all API clients to include client_id in authentication requests.
Or use 
!
after type/scope:
feat!: change authentication endpoint
feat(api)!: remove deprecated /login endpoint
使用
BREAKING CHANGE:
页脚标记不兼容的API变更：
feat(api): change authentication endpoint

BREAKING CHANGE: The /auth endpoint now requires a client_id parameter.
Update all API clients to include client_id in authentication requests.
或在类型/范围后使用
!
：
feat!: change authentication endpoint
feat(api)!: remove deprecated /login endpoint

Issue References

关联议题

Reference issues and pull requests:
fix(auth): resolve session timeout bug

Fixes #123
Closes #456
Related to #789
Common reference types:
  • Fixes #123
    - Closes the issue
  • Closes #123
    - Closes the issue
  • Resolves #123
    - Closes the issue
  • Related to #123
    - References without closing
  • See also #123
    - Additional reference
关联议题和拉取请求：
fix(auth): resolve session timeout bug

Fixes #123
Closes #456
Related to #789
常见关联类型：
  • Fixes #123
    - 关闭议题
  • Closes #123
    - 关闭议题
  • Resolves #123
    - 关闭议题
  • Related to #123
    - 关联但不关闭
  • See also #123
    - 额外关联

Co-authors

协作者

Credit multiple contributors:
feat: add data export feature

Co-authored-by: Jane Doe <jane@example.com>
Co-authored-by: John Smith <john@example.com>
标注多位贡献者：
feat: add data export feature

Co-authored-by: Jane Doe <jane@example.com>
Co-authored-by: John Smith <john@example.com>

Complete Examples

完整示例

Simple Feature

简单功能

feat: add password reset functionality
feat: add password reset functionality

Feature with Scope

带范围的功能

feat(api): add rate limiting for endpoints
feat(api): add rate limiting for endpoints

Bug Fix with Body

带正文的Bug修复

fix(api): handle rate limit errors from GitHub

When GitHub API returns 429 status, retry the request
with exponential backoff up to 3 attempts before failing.

Fixes #234
fix(api): handle rate limit errors from GitHub

When GitHub API returns 429 status, retry the request
with exponential backoff up to 3 attempts before failing.

Fixes #234

Breaking Change

破坏性变更

feat(api)!: redesign webhook payload structure

BREAKING CHANGE: Webhook payloads now use a nested structure.

Before:
{
  "event": "issue.created",
  "data": {...}
}

After:
{
  "type": "issue",
  "action": "created",
  "payload": {...}
}

Clients must update their webhook handlers to use the new structure.
feat(api)!: redesign webhook payload structure

BREAKING CHANGE: Webhook payloads now use a nested structure.

Before:
{
  "event": "issue.created",
  "data": {...}
}

After:
{
  "type": "issue",
  "action": "created",
  "payload": {...}
}

Clients must update their webhook handlers to use the new structure.

Refactoring

代码重构

refactor(services): extract validation to concern

Move common validation logic from multiple services into
a shared ValidationConcern module. No behavior changes.
refactor(services): extract validation to concern

Move common validation logic from multiple services into
a shared ValidationConcern module. No behavior changes.

Multiple Footers

多页脚

fix(auth): resolve concurrent login race condition

Add database-level locking to prevent race condition when
multiple login attempts occur simultaneously for the same user.

Fixes #567
Related to #432
Reviewed-by: Jane Doe <jane@example.com>
fix(auth): resolve concurrent login race condition

Add database-level locking to prevent race condition when
multiple login attempts occur simultaneously for the same user.

Fixes #567
Related to #432
Reviewed-by: Jane Doe <jane@example.com>

Best Practices

最佳实践

Do:

建议：

✅ Use present tense imperative mood ("add" not "added") ✅ Keep first line under 50 characters when possible ✅ Reference issues/PRs in footer ✅ Explain "why" in body, not "what" (code shows what) ✅ Break up large changes into multiple commits ✅ Make commits atomic (one logical change per commit)
✅ 使用现在时态祈使语气（用“add”而非“added”） ✅ 尽可能将首行控制在50字符以内 ✅ 在页脚关联议题/PR ✅ 在正文中解释“原因”而非“内容”（代码已展示内容） ✅ 将大型拆分为多个提交 ✅ 保持提交原子性（每个提交对应一个逻辑变更）

Don't:

避免：

❌ Use vague descriptions ("fix stuff", "updates") ❌ Combine multiple unrelated changes in one commit ❌ Capitalize first letter of description ❌ End description with period ❌ Use past tense ("added", "fixed") ❌ Commit broken code (each commit should work)
❌ 使用模糊描述（如“修复问题”、“更新内容”） ❌ 在一个提交中合并多个不相关变更 ❌ 描述首字母大写 ❌ 描述结尾加句号 ❌ 使用过去时态（如“added”、“fixed”） ❌ 提交无法运行的代码（每个提交都应能正常工作）

Summary

总结

Conventional Commits provide:
  • ✅ Clear, consistent commit history
  • ✅ Better collaboration through explicit intent
  • ✅ Easier code review and git history navigation
  • ✅ Improved project documentation through structured messages
Key formula:
<type>(<scope>): <description>

[body]

[footer]
For detailed examples and edge cases, see 
references/commit-examples.md
.
Conventional Commits可带来：
  • ✅ 清晰、一致的提交历史
  • ✅ 通过明确意图提升协作效率
  • ✅ 更易进行代码审查和Git历史导航
  • ✅ 通过结构化消息改进项目文档
核心公式：
<type>(<scope>): <描述>

[正文]

[页脚]
如需详细示例和边缘情况说明，请查看
references/commit-examples.md
。