Conventional Commits 团队使用文档
Conventional Commits 团队使用文档
一、引言
在软件开发过程中，清晰、一致的提交信息对于项目的维护、协作以及自动化流程的实施至关重要。Conventional Commits 规范为我们提供了一种标准化的提交信息格式，有助于提高团队协作效率，提升项目的可维护性。本文档旨在介绍 Conventional Commits 规范在本团队项目中的具体使用方法和要求。
二、Conventional Commits 规范概述
Conventional Commits 规范的提交信息由以下几部分组成：
<类型>[可选 范围]: <描述>[可选 正文][可选 脚注]
2.1 类型（type）
类型指明了本次提交的性质，常见的类型及其含义如下：
| 类型 | 描述 |
|---|---|
| feat | 新增功能 |
| fix | 修复 bug |
| docs | 文档更新 |
| style | 代码格式调整（不影响代码逻辑） |
| refactor | 代码重构（既非新增功能，也非修复 bug） |
| test | 添加或修改测试代码 |
| chore | 构建过程或辅助工具的变动 |
2.2 范围（scope）
范围是可选的，用于说明本次提交影响的范围，例如某个模块、功能点或技术组件等。例如，feat(user): 添加用户注册功能 中的 user 就是范围，表示该提交影响的是用户模块。
2.3 描述（description）
描述简要概括了此次提交的主要内容，需使用祈使句，首字母小写，且结尾不要加句号。例如，fix(login): 修复登录验证失败的问题 中的 修复登录验证失败的问题 就是描述。
2.4 正文（body）
正文是可选的，用于进一步阐述提交的详细信息，如修改的原因、背景等。
2.5 脚注（footer）
脚注同样是可选的，一般用于记录重大变更、关联的 issue 编号等。例如，Resolves: #123 表示该提交解决了编号为 123 的 issue。
三、团队使用规则
3.1 范围定义
根据项目的特点，我们对提交信息中“范围”的定义如下：
- 模块范围：对于大型项目，可按照功能模块进行划分，如
user（用户模块）、order（订单模块）、product（商品模块）等。 - 功能范围：针对具体的功能点，如
login（登录功能）、payment（支付功能）、search（搜索功能）等。 - 技术范围：涉及技术组件或工具的提交，如
frontend（前端框架）、backend（后端服务）、database（数据库）等。
3.2 提交频率和粒度
- 每次提交应该是一个相对独立、完整的功能或修复，避免将多个不相关的变更合并在一次提交中。
- 提交信息能够清晰地反映本次变更的主要内容，便于团队成员快速理解。
3.3 审核机制
在代码审查过程中，审查人员需要对提交信息进行审核，确保其符合 Conventional Commits 规范。对于不符合规范的提交，要求开发者进行修改。
四、提交规范细则
4.1 原子提交原则
-
按功能模块拆分
每次提交必须限定在单一逻辑功能或修复范围内，禁止跨模块/跨功能的"大包提交"。例如：- 前端UI调整与后端API修改需分开提交
- 用户模块与订单模块的改动不可合并提交
- 功能实现与配套测试代码需分开提交（特殊情况除外）
-
避免无关修改
提交内容必须与本次变更直接相关，禁止夹带其他无关修改。例如：- 修复bug时不应同时调整代码格式
- 新增功能时不应修改其他模块的配置文件
- 文档更新需单独提交，不与代码变更混合
4.2 提交粒度指南
-
功能开发
# 正确示例：按功能点拆分 feat(user): 添加用户注册表单验证 feat(order): 实现订单支付状态查询接口# 错误示例：跨功能大包提交 feat: 添加用户系统和订单支付功能 -
Bug修复
# 正确示例：精确定位问题 fix(login): 修复用户名包含特殊字符时登录失败的问题 fix(api): 修复订单列表接口返回数据格式错误# 错误示例：模糊描述问题 fix: 修复一些登录问题 -
代码重构
# 正确示例：按重构对象拆分 refactor(user): 将用户认证逻辑提取为独立服务 refactor(order): 优化订单状态机实现# 错误示例：笼统重构 refactor: 重构系统代码
4.3 特殊情况处理
-
紧急修复（Hotfix）
紧急修复允许临时合并多个相关修改，但必须在提交信息中明确说明：fix(security): 紧急修复SQL注入漏洞（包含数据库脚本更新）1. 修改用户输入过滤逻辑 2. 更新数据库字段长度限制 3. 添加SQL查询参数化处理BREAKING CHANGE: 数据库字段长度变更，需执行迁移脚本 -
依赖更新
第三方依赖更新需单独提交，并注明更新原因：chore(deps): 更新React到18.2.0版本- 修复已知安全漏洞CVE-2023-12345 - 支持新的并发渲染特性
五、版本控制工作流
5.1 分支提交规范
-
主分支（main/master）
- 仅接受通过CI/CD流程的自动合并
- 禁止直接提交代码到主分支
-
特性分支（feature/*）
- 遵循"一个特性一个分支"原则
- 分支命名格式：
feature/<类型>-<范围>-<简要描述>
# 示例 feature/feat-user-registration feature/fix-login-validation -
修复分支（fix/*）
- 用于紧急修复生产环境问题
- 直接从主分支创建，修复后合并回主分支和开发分支
# 示例 fix/hotfix-sql-injection
5.2 拉取请求（PR）规范
-
标题格式
PR标题必须符合Conventional Commits格式，例如：[feat] 用户模块 - 添加邮箱验证功能 [fix] 支付模块 - 修复微信支付签名错误 -
描述要求
- 详细说明变更内容和影响范围
- 关联相关的issue编号
- 提供测试覆盖情况说明
### 变更内容 1. 添加邮箱格式验证正则表达式 2. 实现邮箱验证码发送功能 3. 更新用户注册流程### 测试覆盖 - 单元测试覆盖率：95% - 已在测试环境验证通过### 关联Issue Closes #123
六、违规处理机制
-
自动化拦截
通过Git钩子和CI/CD流程自动拦截不符合规范的提交：- 提交信息格式校验不通过时阻止提交
- PR标题不符合规范时自动标记为待修改
-
人工干预
对于首次违规的成员：- 由代码审查者指出问题并要求修改
- 记录在团队知识库的"常见错误案例"中
-
重复违规处理
对于多次违反提交规范的成员：- 安排一对一代码规范辅导
- 在团队周会上进行案例分析
- 影响季度绩效考核评分
七、附录
7.1 提交信息示例
feat(user): 添加用户注册功能在用户模块中新增了注册功能，支持邮箱和手机号注册。Resolves: #123
fix(login): 修复登录验证失败的问题由于密码加密算法错误，导致部分用户登录失败。现已经修复该问题。BREAKING CHANGE: 密码加密算法更新，旧密码需要重新设置。
7.2 参考链接
- Conventional Commits 官方文档：https://www.conventionalcommits.org/