conventional-commits

Conventional Commits

编写标准化的语义化提交消息，以支持自动版本管理和变更日志生成。

核心工作流

1. 分析变更：检查已暂存的文件和修改
2. 确定类型：选择适当的提交类型（feat、fix 等）
3. 确定范围：可选，注明受影响的组件/模块
4. 编写描述：用祈使语气简洁概述
5. 添加正文：可选，提供详细说明
6. 添加页脚：注明破坏性变更、问题引用

提交消息格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

提交类型

类型	描述	Semver	示例
feat	新功能	MINOR	feat: add user authentication
fix	修复错误	PATCH	fix: resolve login redirect loop
docs	仅文档变更	-	docs: update API reference
style	格式、空白字符	-	style: fix indentation in utils
refactor	代码变更，不涉及新功能或修复	-	refactor: extract validation logic
perf	性能改进	PATCH	perf: optimize database queries
test	添加或修复测试	-	test: add unit tests for auth
build	构建系统、依赖项	-	build: upgrade to Node 20
ci	CI/CD 配置	-	ci: add GitHub Actions workflow
chore	维护任务	-	chore: update .gitignore
revert	撤销之前的提交	-	revert: undo feature flag change

范围

范围用于指明代码库中受影响的部分：

# Component/module scopes
feat(auth): add OAuth2 support
fix(api): handle timeout errors
docs(readme): add installation steps

# File-based scopes
style(eslint): update linting rules
build(docker): optimize image size

# Layer scopes
refactor(service): extract user service
test(e2e): add checkout flow tests

破坏性变更

使用 ! 或 BREAKING CHANGE 页脚标记破坏性变更：

# Using ! notation
feat(api)!: change response format to JSON:API

# Using footer
feat(api): change response format

BREAKING CHANGE: Response now follows JSON:API specification.
Clients must update their parsers.

提交消息示例

简单功能

feat: add dark mode toggle

带范围的功能

feat(ui): add dark mode toggle to settings page

带问题引用的错误修复

fix(auth): resolve session expiration race condition

The session refresh was racing with the expiration check,
causing intermittent logouts.

Fixes #234

破坏性变更

feat(api)!: migrate to v2 response format

BREAKING CHANGE: All API responses now use camelCase keys
instead of snake_case. Update client parsers accordingly.

Migration guide: https://docs.example.com/v2-migration

多个页脚

fix(payments): correct tax calculation for EU customers

Updated tax calculation to use customer's billing country
instead of shipping country for digital goods.

Fixes #456
Reviewed-by: Alice
Co-authored-by: Bob <[email protected]>

撤销提交

revert: feat(auth): add OAuth2 support

This reverts commit abc123def456.

Reason: OAuth provider has rate limiting issues in production.
Will re-implement with proper caching.

描述编写指南

应该这样做

• 使用祈使语气：“add”，而不是“added”或“adds”
• 控制在 72 个字符以内
• 以小写字母开头
• 末尾不加句号
• 具体、简洁

不要这样做

• “Fixed bug”（过于笼统）
• “Updated stuff”（描述不清）
• “WIP”（准备就绪后再提交）
• “misc changes”（拆分为多个独立提交）

好的示例

feat: add email verification flow
fix: prevent duplicate form submissions
refactor: extract payment processing to service
perf: cache user preferences in memory
docs: add API authentication examples

不好的示例

# Too vague
fix: fixed it
update: updates

# Wrong tense
feat: added new feature
fix: fixes the bug

# Too long
feat: add a new feature that allows users to export their data in multiple formats including CSV, JSON, and XML

正文编写指南

适合添加正文的情况：

• 变更需要背景或说明
• 逻辑复杂，无法一目了然
• 破坏性变更需要提供迁移信息
• 一次提交包含多个相关变更

fix(cache): invalidate user cache on profile update

Previously, profile updates were not reflected until cache expiry.
This caused confusion when users updated their avatar and didn't
see the change immediately.

The fix adds cache invalidation after successful profile updates
and ensures CDN purge for static assets.

页脚标记

标记	用途	示例
Fixes	关闭问题	Fixes #123
Closes	关闭问题	Closes #456
Refs	引用问题	Refs #789
BREAKING CHANGE	破坏性变更	BREAKING CHANGE: description
Reviewed-by	致谢审阅者	Reviewed-by: Name
Co-authored-by	致谢共同作者	Co-authored-by: Name <email>

与工具集成

Commitlint 配置

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat', 'fix', 'docs', 'style', 'refactor',
        'perf', 'test', 'build', 'ci', 'chore', 'revert'
      ]
    ],
    'scope-case': [2, 'always', 'kebab-case'],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100]
  }
};

Husky 提交前钩子

# .husky/commit-msg
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx --no-install commitlint --edit "$1"

Package.json 设置

{
  "devDependencies": {
    "@commitlint/cli": "^18.0.0",
    "@commitlint/config-conventional": "^18.0.0",
    "husky": "^8.0.0"
  },
  "scripts": {
    "prepare": "husky install"
  }
}

与 Semantic Release 集成

Conventional Commits 支持自动版本管理：

# .releaserc.yml
branches:
  - main
plugins:
  - "@semantic-release/commit-analyzer"
  - "@semantic-release/release-notes-generator"
  - "@semantic-release/changelog"
  - "@semantic-release/npm"
  - "@semantic-release/git"

版本升级规则

提交类型	版本升级	示例
feat	次版本（0.X.0）	1.2.0 → 1.3.0
fix	修订版本（0.0.X）	1.2.0 → 1.2.1
perf	修订版本（0.0.X）	1.2.0 → 1.2.1
BREAKING CHANGE	主版本（X.0.0）	1.2.0 → 2.0.0
其他	不升级	1.2.0 → 1.2.0

提交消息生成器

分析变更时，生成一条提交消息：

# 1. Check staged changes
git diff --cached --name-only

# 2. Analyze change type
# - New files = likely feat
# - Modified test files = test
# - Modified docs = docs
# - Bug-related keywords = fix

# 3. Identify scope from path
# src/components/Button.tsx → components or ui
# src/services/auth.ts → auth or services

# 4. Generate message
feat(ui): add loading state to Button component

最佳实践

1. 每次提交只包含一个逻辑变更：不要混合功能和修复
2. 尽早提交、频繁提交：保持提交小而专注
3. 为审阅者撰写：消息应解释原因，而不只是说明内容
4. 引用问题：适用时链接到工单/问题
5. 统一使用范围：建立团队约定
6. 提交前检查：使用 git diff --cached 核对变更

输出检查清单

每条提交信息都应：

• 以有效类型开头（feat、fix、docs 等）
• 在描述中使用祈使语气
• 将描述控制在 72 个字符以内
• 适用时包含作用域
• 使用 ! 或页脚标记重大变更
• 在页脚中引用相关议题
• 复杂变更应提供正文
• 遵循团队的作用域约定