# Git 提交规范指南


## 一、核心原则（前置要求）
### 1. 操作触发与执行约束
- **触发条件**：必须在**人为明确指定本文档**，且确认目标远程仓库及分支后，方可执行 `git add`/`commit`/`push` 等涉及代码变更的操作。
- **禁止场景**：
  - 禁止在非人为交互场景下自动读取或执行本规范。
  - 若未被人为指定阅读，AI 需立即停止继续读取本文档。
- **重复确认机制**：
  - 禁止在非人为确认情况下执行任何 `git add`/`commit`/`push` 操作。
  - 每次完成 `git add`/`commit`/`push` 后，后续任何 Git 操作均需重新经过人为确认方可执行。
  - 每次执行 `git add`/`commit`/`push` 前，必须**罗列出要提交的文件分类及对应的 commit 内容**，经确认后再执行。

### 2. 提交信息要求
- **清晰可追溯**：准确描述“做了什么”和“为什么做”，避免模糊表述（如“修改代码”“更新文件”）。
- **粒度最小化**：单次提交仅包含一个完整功能/修复/文档更新，禁止混合多类无关变更（如同时开发功能+修复bug需拆分提交）。
- **关联上下文**：涉及需求或Bug时，需在提交信息中关联编号（如 `Fixes: #123`，#123 为Bug编号）。
- **禁止的commit内容**：
  - 禁止提交包含敏感信息（如密码、密钥、个人隐私数据）的代码变更。
  - 禁止提交包含二进制文件（如图片、音频、视频等）的变更。
  - 禁止提交包含自动生成的代码（如编译输出、临时文件）的变更。
  - 禁止commit内容过于笼统，比如“修改了一些代码”、“更新了文档”、“同步工作区改动”等。


## 二、提交格式
### 基础结构
```bash
<类型>(范围): <简短描述>
[可选：详细说明]
[可选：关联信息]
```

- **类型**：标识提交的功能类别（必填）。
- **范围**：标识修改涉及的模块/文件类型（必填）。
- **简短描述**：简洁概括变更内容（必填，中文，≤50字）。
- **详细说明**：复杂变更可换行补充细节（可选,中文）。
- **关联信息**：关联需求ID、Bug号等（可选，格式如 `Ref: #123` 或 `Fixes: #456`）。


## 三、类型与范围定义
### 1. 提交类型
| 类型       | 标识       | 适用场景                                                                 |
|------------|------------|--------------------------------------------------------------------------|
| 新增功能   | `feat`     | 新增代码功能（接口、模块、逻辑）；新增配置项、资源文件（音频、图片等）。   |
| 功能修复   | `fix`      | 修复代码bug、逻辑错误；修复配置错误、资源路径问题。                       |
| 文档更新   | `docs`     | 修改注释、使用手册、API文档；补充README、配置说明。                       |
| 代码优化   | `refactor` | 重构代码（不新增功能/修复bug，仅优化结构、命名、性能）。                 |
| 样式调整   | `style`    | 代码格式调整（缩进、空格、注释格式）；不影响代码逻辑。                   |
| 测试相关   | `test`     | 新增/修改测试用例、测试脚本。                                             |
| 构建/配置  | `chore`    | 调整依赖、构建脚本、环境配置（如修改requirements.txt、Dockerfile）。     |

### 2. 范围定义
- `业务代码`：internal、controllers、services等（业务逻辑、数据处理、业务功能模块）。
- `框架代码`：pkg、middlewares、constants_text等（核心框架、原生功能模块、公共工具类）。
- `配置文件`：config、env、backup等（系统配置、环境变量）。
- `资源文件`：docs、.trae、.env等（非代码文件，如音频、图片、字体等）。
- `无范围`：全局变更（如根目录文档、全局配置）。


## 四、操作规范（需人为确认后执行）
### 1. 暂存（add）流程
1. **文件分类**：按“类型+范围”对修改文件进行分类（如“feat(修改目标)”类文件、“fix(原始代码)”类文件）。
2. **列出文件**：明确列出每类需暂存的文件路径（如：`main/修改目标/device.js`、`src/utils/tool.py`）。
3. **执行暂存**：按分类执行 `git add <文件路径>`，禁止使用 `git add .` 批量暂存。
4. **确认内容**：执行 `git diff --cached` 检查暂存内容，无误后等待人为确认。

### 2. 提交（commit）流程
1. **生成信息**：根据文件分类和修改内容，按规范格式生成commit中文信息（包含类型、范围、描述等）。
2. **展示信息**：清晰展示完整的commit信息（使用中文描述，含详细说明和关联信息）。
3. **执行提交**：经人为确认后，执行 `git commit -m "<commit信息>"`。
4. **限制说明**：使用中文写commit信息

### 3. 推送（push）流程
1. **环境说明**：列出当前本地分支（如：`修改目标_ws`）及可用远程仓库（如：`mjgitlab`/`origin`）。
2. **确认目标**：询问并确认推送的远程仓库及分支（如：`mjgitlab/修改目标_ws`）。
3. **执行推送**：仅在人为确认后执行 `git push <远程仓库> <分支>`。
4. **放弃推送**：若未确认目标或存在冲突风险，放弃推送并提示原因。


## 五、示例
### 1. 新增功能（带关联需求）
- **文件分类**：`feat(修改目标)`  
- **涉及文件**：`main/修改目标/wakeup.js`、`main/修改目标/config/wakeup.json`  
- **Commit信息**：
  ```bash
  feat(修改目标): 新增设备语音唤醒功能
  详细说明：
  - 支持自定义唤醒词（最长8个字符）
  - 新增唤醒成功回调接口
  Ref: #102（关联需求ID）
  ```

### 2. 修复Bug（带问题描述）
- **文件分类**：`fix(原始代码)`  
- **涉及文件**：`src/device/heartbeat.py`  
- **Commit信息**：
  ```bash
  fix(原始代码): 修复设备心跳包发送超时问题
  问题：设备联网后30秒内未发送心跳，导致被误判为离线
  修复：调整心跳包发送间隔为10秒
  Fixes: #567（关联Bug ID）
  ```

### 3. 文档更新
- **文件分类**：`docs(修改目标)`  
- **涉及文件**：`docs/修改目标/tts_api.md`  
- **Commit信息**：
  ```bash
  docs(修改目标): 补充TTS推送接口错误码说明
  新增错误码400（参数无效）、500（服务异常）的处理建议
  ```

### 4. 代码优化
- **文件分类**：`refactor(原始代码)`  
- **涉及文件**：`src/device/connection.py`  
- **Commit信息**：
  ```bash
  refactor(原始代码): 拆分设备连接逻辑为独立函数
  提高代码复用性，便于后续维护
  ```


## 六、规范维护
- 本规范存放于项目根目录 `GIT_COMMIT_GUIDELINES.md`，团队成员需共同遵守。
- 可通过Git钩子（如`pre-commit`）自动校验提交信息格式，不符合时拦截提交。
- 定期同步规范执行问题，根据实际场景补充新类型/范围（如新增`perf`标识性能优化）。