|
|
@@ -0,0 +1,127 @@
|
|
|
+# 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`标识性能优化）。
|
