commits

约定式提交

用于结构化提交消息的规范，可实现自动化变更日志生成和语义化版本控制。

快速参考

格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

常用类型

类型	用途	SemVer
feat	新功能	MINOR
fix	Bug 修复	PATCH
docs	仅文档	-
style	格式化，无代码更改	-
refactor	代码更改，无新功能/Bug 修复	-
perf	性能改进	-
test	添加/修复测试	-
build	构建系统、依赖项	-
ci	CI 配置	-
chore	维护任务	-
revert	回滚之前的提交	-

破坏性变更

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: 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(auth): add OAuth2 support
fix(parser): handle empty arrays
docs(readme): add installation guide
refactor(api): simplify error handling

带正文

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: correct minor typos in code

Reviewed-by: John Doe
Refs: #123

页脚中的破坏性变更

feat: allow config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used
for extending other config files.

使用 ! 和页脚的破坏性变更

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

回滚提交

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

规范规则

必须

1. 提交必须以类型为前缀（feat、fix 等）
2. 类型后必须跟冒号和空格
3. 描述必须紧跟在冒号和空格之后
4. 新功能必须使用 feat
5. Bug 修复必须使用 fix
6. 破坏性变更必须通过在 : 前加 ! 或 BREAKING CHANGE: 页脚来表示
7. BREAKING CHANGE 必须为大写
8. 页脚标记必须使用 - 代替空格（例如 Reviewed-by）

可选

1. 作用域可在类型之后提供：feat(parser):
2. 正文可在描述之后提供（中间空一行）
3. 页脚可在正文之后提供（中间空一行）
4. 可使用 feat 和 fix 之外的其它类型
5. ! 可与 BREAKING CHANGE: 页脚一起使用

大小写敏感性

• 类型：不区分大小写（为保持一致性建议使用小写）
• BREAKING CHANGE：必须为大写
• BREAKING-CHANGE：BREAKING CHANGE 的同义词

SemVer 映射

提交类型	SemVer 递增	版本变更
fix:	PATCH	1.0.0 → 1.0.1
feat:	MINOR	1.0.0 → 1.1.0
BREAKING CHANGE 或 !	MAJOR	1.0.0 → 2.0.0

破坏性变更会覆盖类型 —— fix!: 会导致 MAJOR 递增。

变更日志集成

约定式提交可直接映射到变更日志条目：

提交类型	变更日志部分
feat	新增
fix	修复
perf	变更
refactor	变更
docs	（通常省略或归为变更）
BREAKING CHANGE	在变更/移除中突出显示
revert	移除或修复
安全修复	安全

自动化变更日志生成

conventional-changelog、semantic-release 或 release-please 等工具可以：

• 解析提交消息
• 生成 CHANGELOG.md 条目
• 确定下一个版本号
• 自动创建发布

关于 CHANGELOG.md 格式，请参阅变更日志技能。

常见模式

功能开发

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"

带引用的 Bug 修复

git commit -m "fix(auth): resolve session timeout (#142)"

破坏性变更流程

# Deprecate first
git commit -m "feat(api): add v2 endpoint

DEPRECATED: /api/v1/users will be removed in next major version"

# Later, remove
git commit -m "feat(api)!: remove v1 endpoints

BREAKING CHANGE: /api/v1/* endpoints have been removed.
Use /api/v2/* instead."

常见问题

如果提交符合多种类型怎么办？

尽可能拆分为多个提交。这样可使历史记录更有条理。

如果我使用了错误的类型怎么办？

合并前：使用 git rebase -i 编辑历史记录。 发布后：不太关键 —— 提交会被自动化工具遗漏。

是否所有贡献者都需要使用这一规范？

不需要。使用压缩合并，维护者可以为合并编写合适的消息。

如何处理回退？

revert: <original commit subject>

Refs: <commit SHA>

Git 配置

提交模板

配置 git 使用模板：

git config commit.template .gitmessage

模板文件见 assets/commit-msg.template。

提交前校验

将 assets/validate-commit-msg.sh 与 git hooks 或 CI 配合使用。

工具

工具	用途
commitlint	检查提交信息
commitizen	交互式提交辅助工具
conventional-changelog	生成变更日志
semantic-release	自动化发布
release-please	GitHub 发布自动化

严格禁止事项

• 不要使用含糊的信息（"fix stuff"、"update"、"wip"）
• 不要在单个提交中混入不相关的变更
• 不要遗漏破坏性变更标识
• 未经团队同意，不要使用非标准类型
• 不要忘记在描述和正文之间留空行

提交信息的 Agent 工作流

强制要求：在提出分支名称、提交信息或 PR 描述之前，Agent 必须：

1. 检查所有已变更文件，使用 git status 或 git diff --name-only
2. 审查实际变更，使用 git diff（已暂存和未暂存）
3. 分析所有修改——而不仅仅是对话中提到的文件
4. 基于完整变更集提出建议——包含所有受影响文件，而非部分列表

工作流步骤

# Step 1: Get list of all changed files
git status --short

# Step 2: Review actual changes (for unstaged)
git diff

# Step 3: Review staged changes
git diff --staged

# Step 4: Use the complete changeset to propose:
#   - Branch name
#   - Commit message
#   - PR description

输出格式

当用户要求提交信息时，提供：

1. 分支名称选项（3 个使用约定式前缀的变体）
2. 提交信息变体（简短/中等/详细）
3. PR 描述（概括性描述，不要重复完整变更日志）

所有建议必须基于实际的 git diff 输出，而非假设。

链接

• 官方规范：https://www.conventionalcommits.org/en/v1.0.0/
• 语义化版本：https://semver.org/spec/v2.0.0.html
• 相关：changelog skill — CHANGELOG.md 格式

模板

• commit-msg.template — Git 提交信息模板
• validate-commit-msg.sh — 校验脚本