Git 提交规范实践：Conventional Commits、Commitizen 与 CHANGELOG 自动生成

Posted 2022-01-12 Updated 3 days ago

By Ryan Chen

15~19 min read

统一的 Git 提交规范可以让提交历史更清晰，也能为代码审查、版本发布、CHANGELOG 自动生成和问题追踪提供基础数据。

这篇文章基于 Conventional Commits 规范，整理团队中可落地的提交格式、常见 type、Commitizen、commitlint 和 CHANGELOG 自动化实践。

CI/CD 系列文章

本文属于 Jenkins + GitLab + SonarQube CI/CD 系列，相关内容可以继续阅读：

为什么要制定提交规范

没有规范的提交记录常见问题：

fix bug、update、修改一下 之类信息无法说明变更内容。
代码审查时难以快速理解提交目的。
发布时无法自动生成 CHANGELOG。
回溯线上问题时定位困难。

提交规范的价值：

提升提交记录可读性。
区分需求、修复、文档、构建、CI 等不同变更。
支持语义化版本和 CHANGELOG 自动生成。
让团队协作更稳定。

Conventional Commits 格式

推荐格式：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

示例：

feat(order): 支持微信支付下单

新增微信支付参数校验、签名生成和支付单创建流程。

Closes #123

破坏性变更示例：

feat(api)!: 调整订单查询接口返回结构

BREAKING CHANGE: data 字段由对象改为数组，调用方需要同步适配。

常用 type

type	含义	示例
`feat`	新功能	`feat(user): 新增用户导出`
`fix`	Bug 修复	`fix(order): 修复金额精度问题`
`docs`	文档	`docs: 更新部署说明`
`style`	格式调整	`style: 格式化代码`
`refactor`	重构	`refactor(pay): 拆分支付策略`
`perf`	性能优化	`perf(query): 优化分页查询`
`test`	测试	`test: 补充订单单元测试`
`build`	构建系统	`build: 升级 Maven 插件`
`ci`	CI 配置	`ci: 增加 Jenkins 质量门禁`
`chore`	杂项	`chore: 调整脚本权限`
`revert`	回滚	`revert: 回滚订单导出功能`

scope 与 description

scope 表示影响范围，建议使用模块名或业务域：

feat(user): 新增用户导入
fix(order): 修复订单状态流转
ci(jenkins): 增加 SonarQube 扫描

description 要简短明确，建议：

使用中文或英文都可以，但团队内保持统一。
不要写空泛描述。
尽量说明“做了什么”，而不是“改一下”。

命令行提交

简单提交：

git commit -m "fix(order): 修复订单金额计算精度"

带正文：

git commit

然后按规范填写多行提交信息。

Commitizen

Commitizen 可以通过交互式命令生成规范 Commit。

安装：

npm install -g commitizen cz-conventional-changelog

用户目录配置 .czrc：

{ "path": "cz-conventional-changelog" }

提交：

git cz

commitlint 校验

为了避免规范只停留在口头约定，可以在 CI 或 Git Hook 中校验提交信息。

常用方案：

commitlint
husky
GitLab CI / Jenkins Pipeline 校验

示例：

npm install --save-dev @commitlint/config-conventional @commitlint/cli

commitlint.config.js：

module.exports = { extends: ['@commitlint/config-conventional'] };

生成 CHANGELOG

规范化提交后，可以用 standard-version、semantic-release 等工具生成 CHANGELOG。

示例：

npm install --save-dev standard-version
npx standard-version

CHANGELOG 会根据 feat、fix、breaking change 等信息自动分组。

团队落地建议

先统一 type 和 scope 列表。
在 README 中给出示例。
IDE 可以安装 Git Commit Template 插件。
CI 中增加 commit message 校验。
发布流程中自动生成 CHANGELOG。
Code Review 时关注提交粒度，避免一个 commit 混入多个无关变更。

常见问题

1. 是否必须每个 commit 都非常严格

建议主干、发布分支、合并请求中的 commit 严格遵守。个人临时分支可以适当宽松，但合并前最好 squash 或整理。

2. 中文还是英文

都可以。中文对国内团队更易读，英文对开源项目更通用。关键是团队统一。

3. merge commit 怎么处理

如果使用 Merge Request，可以让 MR 标题遵循 Conventional Commits，并在合并时 squash。

参考资料

指南

License: CC BY 4.0