conventional-commits

Conventional Commits

本技能提供编写符合 Conventional Commits 规范（v1.0.0）的 Git 提交信息指南。

用途

Conventional Commits 是一套规范，旨在为提交信息添加人类和机器可读的含义。它提供了一组简单的规则，用于创建清晰明确的提交历史，从而更轻松地理解项目变更并改善协作。

何时使用此技能

在以下情况下使用此技能：

• 创建 Git 提交
• 审查 PR 中的提交信息
• 编写清晰、结构化的提交信息
• 与多位贡献者协作开发项目

提交信息结构

基本格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

示例

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 - 为用户添加新功能

feat: add export to PDF functionality
feat(api): add webhook signature verification

fix - 修复影响用户的错误

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 - 既不修复错误也不添加功能的代码更改

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

其他类型（较少使用）

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.

范围（可选）

范围用于补充说明代码库中哪些部分发生了更改：

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 - 文档

选择符合项目架构和领域划分的范围。

描述

描述是对代码更改的简短概述：

规则：

• 使用祈使语气和现在时：“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          # Past tense
Fix Memory Leak In File Upload   # Capitalized
Updated email templates.          # Period at end
Lots of changes to the codebase   # Vague

正文（可选）

正文用于补充说明更改的背景：

适合添加正文的情况：

• 需要解释的复杂更改
• 不明显的设计决策
• 重大更改
• 迁移说明

格式：

• 与描述之间空一行
• 像描述一样使用祈使语气
• 每行不超过 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.

页脚（可选）

页脚用于提供提交的元数据：

重大更改

对于不兼容的 API 更改，使用 BREAKING CHANGE: 页脚：

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

问题引用

引用问题和拉取请求：

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 - 补充引用

共同作者

为多位贡献者署名：

feat: add data export feature

Co-authored-by: Jane Doe <[email protected]>
Co-authored-by: John Smith <[email protected]>

完整示例

简单功能

feat: add password reset functionality

带范围的功能

feat(api): add rate limiting for endpoints

带正文的错误修复

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

重大更改

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.

重构

refactor(services): extract validation to concern

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

多个页脚

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 <[email protected]>

最佳实践

建议：

✅ 使用现在时祈使语气（“add”，而不是“added”） ✅ 尽可能将首行控制在 50 个字符以内 ✅ 在页脚中引用问题/PR ✅ 在正文中解释“为什么”，而不是“是什么”（代码会展示是什么） ✅ 将大型更改拆分为多个提交 ✅ 确保提交具有原子性（每个提交只包含一个逻辑更改）

不要：

❌ 使用含糊的描述（“修东西”“更新”） ❌ 在一个提交中合并多个无关更改 ❌ 将描述的首字母大写 ❌ 在描述末尾加句号 ❌ 使用过去时（“已添加”“已修复”） ❌ 提交无法运行的代码（每次提交都应可正常工作）

总结

Conventional Commits 提供：

• ✅ 清晰、一致的提交历史
• ✅ 通过明确表达意图，促进更好的协作
• ✅ 便于代码审查和浏览 git 历史
• ✅ 通过结构化消息改进项目文档

关键公式：

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

[body]

[footer]

如需查看详细示例和边缘情况，请参阅 references/commit-examples.md。