Git提交规范

Conventional Commits 提交信息规范

提交类型

类型清单

Requirement：提交信息必须以 Conventional Commits 类型开头，类型与描述之间用冒号加空格分隔。

类型	说明	示例
`feat`	新功能	`feat: add user registration API`
`fix`	缺陷修复	`fix: resolve null pointer in order service`
`docs`	文档变更	`docs: update API README`
`style`	代码格式调整（不影响逻辑）	`style: format code with prettier`
`refactor`	重构（非新功能、非修复）	`refactor: extract user service interface`
`perf`	性能优化	`perf: reduce database query latency`
`test`	测试相关	`test: add unit tests for auth module`
`chore`	工程杂项（构建、依赖、配置）	`chore: bump lodash to 4.17.21`
`ci`	CI/CD 配置变更	`ci: add lint job to pipeline`
`build`	构建系统或外部依赖变更	`build: upgrade webpack to v5`
`revert`	回滚提交	`revert: revert feat: add user registration`

破坏性变更标记

Requirement：包含破坏性变更（Breaking Change）时，类型后加 !，并在正文 footer 中以 BREAKING CHANGE: 开头说明。

feat!: change user API response schema

BREAKING CHANGE: `user.name` field renamed to `user.fullName`.

格式约定

标准格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

规则

Requirement：首行（subject）长度 ≤ 72 字符，超出需换行到 body。
Requirement：subject 使用祈使句（动词原形），如 add、fix、remove，不使用过去式（added、fixed）。
Requirement：subject 末尾不加句号。
Standard：subject 首字母小写（除非是专有名词或缩写）。
Standard：scope 可选，用于标识变更影响的模块，放在圆括号内，如 feat(auth): add login。
Standard：body 与 subject 之间空一行；body 每行 ≤ 72 字符；body 用于说明 为什么（Why）而非 怎么做（How）。
Suggestion：footer 可包含关联任务、Co-authored-by、BREAKING CHANGE 等元信息。

scope 命名

Standard：scope 使用模块名的小写形式，与代码目录结构一致。
Standard：多模块变更可省略 scope，或使用逗号分隔（不推荐，应拆分为多个提交）。

feat(auth): add OAuth2 login
fix(order): correct total price calculation
chore(deps): upgrade react to 18

提交粒度

原子性原则

Requirement：每个提交只做一件事（Atomic Commit），禁止将多个不相关变更混入一个提交。
Standard：提交大小建议 ≤ 400 行变更（不含自动生成文件），超过应拆分。
Standard：一个提交必须可独立通过编译与测试（Green Commit），禁止提交半成品。

拆分策略

Standard：按功能点拆分，每个功能点一个 feat 提交。
Standard：重构与功能变更分开提交，重构用 refactor，功能用 feat/fix。
Standard：格式化变更（style）单独提交，不与逻辑变更混合，便于 Code Review。

示例

Good：

feat(auth): add user registration endpoint
feat(auth): add email verification flow
test(auth): add registration unit tests
docs(api): document registration API

Bad（一个提交做了四件事）：

add registration, fix login bug, format code, update docs

示例

简单提交

feat: add dark mode toggle

带 scope

fix(payment): correct currency conversion rate

带 body

refactor(user): split UserService into query and command handlers

The original UserService had grown to over 800 lines handling both
read and write operations. Splitting improves testability and follows
CQRS principles. No behavior change expected.

feat(order): add bulk order export

Closes #1234

带 BREAKING CHANGE

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: /api/v1/* endpoints are removed. Clients must migrate
to /api/v2/* before upgrading to this version. Migration guide:
https://docs.example.com/migration/v1-to-v2

revert 提交

revert: revert "feat: add dark mode toggle"

This reverts commit a1b2c3d. Dark mode caused contrast issues in
accessibility audit. Will re-introduce after fix.

反模式

禁止的提交信息

反模式	问题
`update` / `fix` / `tmp` / `wip`	无意义，无法追溯变更内容
`fixed bug`	未说明修了什么 bug
`add feature`	未说明加了什么功能
`WIP: ongoing work`	半成品提交，破坏主干可构建性
`fix review comments`	未说明具体变更内容
`update as per review`	同上
`merge main into feature`	应使用 rebase，且 squash 时该提交应被压缩

禁止的提交内容

❌ 提交中包含密钥、token、密码、证书等敏感信息。
❌ 提交中包含 node_modules、dist、build 等构建产物。
❌ 提交中包含个人 IDE 配置（.idea/、.vscode/ 除非团队统一维护）。
❌ 提交中包含操作系统临时文件（.DS_Store、Thumbs.db）。
❌ 一个提交同时包含业务代码变更与依赖升级（应拆分）。

工具支持

Standard：建议在仓库中配置以下工具强制规范：

commitlint + husky：在 commit-msg 钩子中校验提交信息格式。
commitizen：交互式生成规范提交信息。
CI 校验：在 PR 流水线中对所有提交执行 commitlint 检查。

commitlint.config.js 示例：

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