汤不热吧详解 Git 提交规范：如何利用 Conventional Commits 构建自动化的版本发布日志
Git 提交规范是现代软件开发中不可或缺的一环。一个清晰、一致的提交历史不仅能帮助团队成员快速理解变更内容，更是实现自动化版本发布和生成 CHANGELOG 的基石。
Conventional Commits（约定式提交）就是这样一种轻量级的规范，它为提交信息提供了一套简单、明确的规则，使其能够映射到 Semantic Versioning (SemVer)。
1. Conventional Commits 规范基础
约定式提交的格式非常简单，但功能强大：
<type>(<scope>)?(!): <description>
[optional body]
[optional footer(s)]
核心要素
- Type (必需): 提交的类型，是决定版本号升级的关键。
- feat: 新增功能（对应 SemVer 的 MINOR 版本升级）。
- fix: 修复 Bug（对应 SemVer 的 PATCH 版本升级）。
- docs: 文档变更。
- style: 代码格式化，不影响代码逻辑。
- refactor: 重构代码，既不修复 Bug 也不新增功能。
- perf: 性能优化。
- test: 增加或修改测试。
- chore: 杂项事务，如构建过程或辅助工具的变动。
- build: 影响构建系统或外部依赖的更改（例如 scope: npm, scope: yarn）。
- ci: 持续集成相关的改动（例如 scope: travis, scope: jenkins）。
- Scope (可选): 指明本次提交影响的范围，如模块名、功能名（e.g., feat(auth):）。
-
Description (必需): 简短的描述，100字以内。
-
Breaking Change (!): 如果提交包含了破坏性变更，必须在 type/scope 后面添加一个 !，这会触发 SemVer 的 MAJOR 版本升级。
2. 实践：利用工具链实现自动化
为了保证团队成员严格遵守规范，我们通常使用工具进行强制校验和自动化版本管理。这里我们使用 Node.js 生态中最流行的工具：commitlint 进行校验，以及 standard-version 进行版本发布。
2.1 初始化项目并安装依赖
假设你已经初始化了一个 Node.js 项目 (npm init -y)。
# 安装开发依赖
npm install -D @commitlint/config-conventional @commitlint/cli husky standard-version
# 初始化 Husky (用于配置 Git Hooks)
npx husky install
2.2 配置 Commitlint 提交校验
创建 commitlint.config.js 文件来配置校验规则：
// commitlint.config.js
module.exports = {
// 继承最常用的约定式提交规范
extends: ['@commitlint/config-conventional'],
rules: {
// 确保 type 遵循规范列表
'type-enum': [
2,
'always',
['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'chore', 'build', 'ci']
],
// 描述长度限制
'header-max-length': [2, 'always', 100]
}
};
接下来，使用 Husky 设置一个 commit-msg 钩子，确保在用户提交时，Git 自动调用 commitlint 进行检查。
npx husky add .husky/commit-msg 'npx commitlint --edit "$1"'
现在，如果你尝试提交一个不规范的信息（如 git commit -m ‘wrong message’），Git 提交将失败。
2.3 规范化提交示例
当你使用规范提交时，将顺利通过：
# 新增功能，触发 MINOR 升级
git commit -m "feat(user): add user profile endpoint"
# 修复 Bug，触发 PATCH 升级
git commit -m "fix: correct off-by-one error in pagination logic"
# 包含破坏性变更，触发 MAJOR 升级
git commit -m "feat(config)!: remove deprecated API keys"
git commit -m "BREAKING CHANGE: The config structure has changed, see documentation for migration."
注意：对于破坏性变更，standard-version 工具只需要识别到 ! 或 BREAKING CHANGE: 关键字即可触发 MAJOR 升级。
3. 自动化版本发布与日志生成
standard-version 工具可以读取你的 Git 历史，根据提交类型（feat, fix, !）自动：
- 计算下一个版本号 (SemVer)。
- 更新项目的版本文件（如 package.json）。
- 生成或更新 CHANGELOG.md。
- 创建 Git Tag。
3.1 配置 npm 脚本
编辑 package.json，添加 release 脚本：
{
"scripts": {
"release": "standard-version"
}
}
3.2 运行版本发布流程
假设你已经有了两次规范提交 (fix 和 feat)。
步骤 1：第一次发布
# 首次运行，通常从 v1.0.0 或 v0.0.1 开始
npm run release -- --first-release
步骤 2：进行后续提交
假设我们又增加了一个新功能（feat）。
git commit -m "feat: introduce caching mechanism"
git push
步骤 3：发布新版本
运行 npm run release，standard-version 会检测到 feat 提交，自动将版本号从 v1.0.0 升级到 v1.1.0。
npm run release
运行结果：
- package.json 中的版本号更新到 v1.1.0。
- 生成 CHANGELOG.md，其中包含了自上次版本发布以来所有 feat 和 fix 提交的列表。
- 在 Git 中打上 v1.1.0 标签。
自动生成的 CHANGELOG.md 示例片段
## 1.1.0 (2023-10-26)
### Features
* introduce caching mechanism (9a1b3c4)
### Bug Fixes
* correct off-by-one error in pagination logic (e7d8f90)
总结
通过采纳 Conventional Commits 规范，并结合 commitlint 进行提交校验，以及 standard-version 进行自动化版本发布，你的项目将拥有清晰、可追溯的提交历史和自动生成的版本发布日志。这不仅降低了人工维护成本，也为后续集成 CI/CD 流程提供了坚实的基础。