提交信息规范

作为资深的软件工程实践专家，根据Conventional Commits规范和团队协作的实际需要，这里提供一份简洁、高效的提交信息编写模板与最佳实践。使用这个模板能确保提交信息具有一致性、可读性和可维护性，从而提高团队协作效率。

---

### **提交信息模板**

```
<类型>[可选范围]: <简要描述>

[可选正文]

[可选脚注/引用]
```

---

### **字段说明与规范**

#### 1. `<类型>`  
提交信息的核心字段，指定提交的类别。以下是Conventional Commits推荐的常用类型：
- **feat**: 添加新特性 (feature)
    - 示例: `feat: 添加用户登录功能`
- **fix**: 修复缺陷 (bug fix)
    - 示例: `fix: 修复密码验证的边界问题`
- **docs**: 修改文档 (文档相关的更改，不涉及代码)
    - 示例: `docs: 更新API接口文档`
- **style**: 代码格式（不影响功能，例如空格、格式化等）
    - 示例: `style: 统一eslint格式化规则`
- **refactor**: 代码重构 (既不修复 bug 也不添加功能)
    - 示例: `refactor: 优化数据库查询逻辑`
- **perf**: 性能优化
    - 示例: `perf: 提高图片加载速度`
- **test**: 添加/修改测试代码
    - 示例: `test: 增加Edge浏览器的兼容性测试`
- **chore**: 其他更改 (不影响源代码或测试；如构建工具调整)
    - 示例: `chore: 更新webpack配置`
- **ci**: 持续集成配置/脚本的修改
    - 示例: `ci: 修正CI触发条件`
- **build**: 构建系统或外部依赖相关的更改
    - 示例: `build: 升级node.js版本为16`

#### 2. `[可选范围]`  
模块或功能的范围（可选），标明所影响的特定子模块，以括号包裹，帮助快速定位变更内容。
- 示例: `feat(登录): 支持第三方OAuth登录`

#### 3. `<简要描述>`  
简要描述本次提交的变更内容，需做到**清晰、具体、简洁**。使用祈使句表述行动。

#### 4. `[可选正文]`  
进一步详细说明更改的**动机、具体实现或背景**，适用于复杂提交。应使用完整句式。

#### 5. `[可选脚注/引用]`  
用来标明任务的追踪信息（如JIRA、GitHub issue）。也可用于标记**潜在影响**或**后续步骤**。
- 示例:  
  - `BREAKING CHANGE: 重构用户登录接口，原有方法已弃用`
  - `Closes #1234`

---

### **最佳实践指导**

1. **保持简洁清晰**: 提交信息是团队交流的桥梁，避免冗长和模糊描述。每次提交只聚焦一个变更。
2. **确保原子性**: 每次提交应该是不可分割的逻辑单元，提交粒度越细，理解和回退成本越低。
3. **常用正则约束检查**:
   - 格式: `<类型>[可选范围]: 描述`
   - 描述开头小写，可省略标点符号。
4. **中文还是英文**: 依据团队习惯选择。保持一致性，优先考虑项目受众（如国际化项目建议使用英文）。

---

### **示例汇编**
#### 示例1: 单一功能开发
```
feat(支付): 添加支付宝支付功能

为结算模块新增了支付宝支付集成，包括请求签名与结果校验。
```

#### 示例2: Bug修复
```
fix(路由): 修复动态路由解析错误

修复了动态路由在特殊字符（如`#`和`?`）场景下无法正常解析的问题。

Closes #567
```

#### 示例3: 文档更新
```
docs(部署指南): 更新Kubernetes部署说明
```

#### 示例4: 特殊情况（兼容性破坏）
```
refactor(会员模块): 重构会员等级接口

BREAKING CHANGE: 会员等级字段增加了新属性`points`，原有方法`getLevel()`已移除。
```

#### 示例5: 配置调整
```
chore(deps): 升级eslint版本到8.x
```

---

### 使用效果
- **历史可追溯**: 提交信息完全符合项目变更历史的阅读习惯。
- **工具兼容好**: 常见工具（如Changelog生成器）和CI/CD工具能直接利用此规范。
- **团队效率提升**: 团队清楚分工与改动背景，快速定位解决问题。

能符合Conventional Commits也是团队开发成熟度的重要标志，建议团队长期坚持，以帮助维护可持续发展的代码库。

在团队协作中，规范的提交信息有助于代码的可读性、追溯和团队间的快速理解。以下是一个基于最佳实践的提交信息编写模板和说明。

---

### 提交信息编写模板

#### 1. 标题 (Subject line)
   - **格式**: `{类型}: {简要描述变更}`
   - **要求**:
     - 使用简洁直白的语言，概括本次提交的主要变更内容。
     - 控制在 50 个字符以内，且不要以句号结尾。

#### 标题内的 {类型} 通常可使用以下分类：
   - **feat**: 增加新功能，例如 `feat: 新增用户登录功能`
   - **fix**: 修复缺陷，例如 `fix: 修复表单提交时的验证错误`
   - **refactor**: 重构代码，不涉及功能改动，例如 `refactor: 优化登录逻辑代码`
   - **docs**: 只修改文档，例如 `docs: 更新 README 中的安装说明`
   - **style**: 代码样式调整，不影响功能，例如 `style: 调整代码缩进`
   - **test**: 添加或修改测试文件，例如 `test: 增加单元测试用例`
   - **chore**: 杂项更新，例如工具、构建过程或依赖变更，例如 `chore: 更新 eslint 配置`
   - **perf**: 提升性能，例如 `perf: 优化查询性能减少响应时间` 
   - **build**: 构建系统或依赖变更，例如 `build: 升级 webpack 版本`
   - **ci**: 持续集成相关变更，例如 `ci: 修复 Jenkins 构建失败的问题`

#### 2. 描述 (Body)
   - 用一两段详细说明变更内容。
   - **要求**:
     - 清楚说明为何做出此次变更及其背景。
     - 说明变更的内容、影响以及任何潜在的问题。
     - 列出解决方案的简要描述。
   - 示例：
     ```
     - 增加了用户登录接口，支持用户名和密码鉴权。
     - 对接了后端 API，统一错误码处理。
     - 更新了相关 UI 界面的输入框交互逻辑。
     ```

#### 3. 关联问题 (Footer)
   - **格式**: 引用相关的 issue 号码或任务编号。
   - 示例：
     ```
     Closes #123
     Relates to AB-456
     ```

---

### 示例提交信息

```
feat: 新增用户登录功能

- 增加用户登录表单以及后端接入逻辑。
- 完成错误码解析与友好提示功能。
- 测试覆盖用户登录场景，包括异常输入。
- 更新相关文档以说明操作方式。

Closes #101
```

---

### 编写提交信息的注意事项
1. **保持清晰简洁**：主题行直接点明改动的核心点，避免歧义或多余修饰。
2. **一条提交一个目的**：将功能变更或修复内容拆分成多次提交，避免“大提交”。
3. **保持可读性**：避免使用缩写、行文通顺，非技术成员也能大致读懂。
4. **主动关联 Issue 或任务编号**：帮助团队追踪功能背景和变更记录。
5. **团队一致性**：确保所有提交信息都遵循统一约定。

通过上述模板和实践，不仅可以保持清晰记录，还能显著提升协作效率和代码历史的可追踪性。

在团队协作的版本控制中，统一、清晰的提交信息格式有助于提升沟通效率、代码可维护性，以及版本回溯的便利性。以下是一份提交信息编写的标准模板与最佳实践指导：

---

### **提交信息的通用模板**

```
<类型>: <简要描述提交内容>

<空行>

<详细说明> (可选，根据需要)

<解决的问题或背景> (可选，与关联任务/问题编号相关时提及)
```

---

### **字段详解与规范**

#### **1. 类型**
提交信息的第一部分用于标明提交的类型，帮助团队快速了解改动的性质。常见类型如下：
- **feat**: 新功能（Feature）
- **fix**: 修复 Bug
- **docs**: 文档变更
- **style**: 代码风格或格式调整（不影响功能，如空格、格式化等）
- **refactor**: 代码重构（不影响功能和外部行为）
- **test**: 添加或修改测试
- **chore**: 构建任务或工具配置变动（例如升级依赖）
- **perf**: 性能优化
- **ci**: 持续集成相关的改动

**示例**:
```
feat: 新增用户注册功能
fix: 修复登录页面显示问题
style: 规范化代码缩进
chore: 更新全局依赖至最新版本
```

---

#### **2. 简要描述提交内容**
- 使用 **命令式动词**，如“新增”、“修复”、“更新”、“移除”等（英语可使用原型动词，如“add”、“fix”）。
- 描述应该简洁明了，概括本次提交的主要目标。
- 尽量控制在 50 个字符以内，便于提交记录查看。

**示例**:
```
fix: 修复注册接口为空时的崩溃问题
docs: 新增 README 场景演示图片
```

---

#### **3. 详细说明（可选）**
- 对提交内容进行更加完整的详细描述。
- 说明变更的原因、修改的细节、受影响的模块等。
- 针对复杂的改动，可以说明背景上下文或依赖的新内容。

**示例**:
```
refactor: 优化数据处理逻辑以减少调用延迟

优化了数据表分页查询的 SQL 在后台的处理逻辑，用了索引降低复杂度。
提升了平均接口响应速度从 300ms 到 150ms。
```

---

#### **4. 关联任务/问题编号（可选）**
- 若提交与某个任务（如 JIRA、Trello）或问题（Issue）关联，应在此指明（如 `#123` 或 `JIRA-456`）。
- 使用简单标记帮助追踪问题来源。

**示例**:
```
fix: 修复文件上传超时导致的界面卡死 (#125)
```

---

### **标准提交信息示例**

1. **修复问题**
```
fix: 修复登录页面显示问题

修复了由于 CSS 文件路径错误导致的登录页面无法正常加载的问题。
这个问题在生产环境可以通过正确配置路径避免。升级版本 v1.2.3 解决。
```

2. **新增功能**
```
feat: 新增忘记密码功能

在登录页新增了“忘记密码”功能。
用户可以通过验证邮箱地址以设置新的密码。
关联需求：#789
```

3. **优化性能**
```
perf: 优化图片的加载逻辑

通过引入延迟加载技术（lazy load），减少不必要的图片资源初始加载。
此改动使页面加载时间减少了 40%，提升了用户体验。
```

4. **文档更新**
```
docs: 更新使用指南文档

新增了指南文档对 API 登陆权限部分的描述内容。
```

---

### **版本控制提交的最佳实践**

1. **保持简单、清晰**
   - 提交信息是“给人看的”，优先考虑可读性。
   - 避免冗长的描述，复杂内容请写入详细说明部分。

2. **一份提交聚焦一个主题**
   - 每次提交只解决一类问题或做一类改动，避免混杂。

3. **与任务或问题编号关联**
   - 提交修复时，尽量在信息中体现与问题的关联。

4. **遵循团队约定**
   - 团队应该制定并遵守一套统一的提交规范。

通过遵循这一标准，团队的提交历史将更加结构化和易于理解，从而提升代码协作效率和长期维护性。