# Git 提交规范

本文档定义 AIBIS Dream 项目的 Git 提交消息格式、分支命名规范与最佳实践。

---

## 提交消息格式

采用 [Conventional Commits](https://www.conventionalcommits.org/) 规范，结构如下：

```
<type>(<scope>): <subject>

[body]

[footer]
```

### 各部分说明

| 部分 | 是否必填 | 说明 |
|------|---------|------|
| type | 必填 | 提交类型，英文小写关键词 |
| scope | 可选 | 影响的模块/系统，用括号包裹 |
| subject | 必填 | 简要描述，中文，不超过 50 字，不加句号 |
| body | 可选 | 详细说明变更原因、背景和影响 |
| footer | 可选 | 关联 issue 编号或标注 BREAKING CHANGE |

### 格式要求

- `type` 与 `scope` 之间无空格
- `:` 后面加一个空格再写 `subject`
- `subject` 使用中文，动词开头（添加、修复、优化、重构、更新……）
- `body` 与 `subject` 之间空一行
- 每行不超过 72 个字符

---

## Type 类型定义

针对游戏开发场景扩展了标准 Conventional Commits 类型：

| type | 说明 | 示例 |
|------|------|------|
| feat | 新功能或功能增强 | 添加线索收藏功能 |
| fix | Bug 修复 | 修复对话跳过时崩溃的问题 |
| art | 美术资源变更（贴图、模型、动画、Spine 等） | 替换火山头部模型和贴图 |
| audio | 音频资源变更（音效、音乐、FMOD bank 等） | 添加酒吧环境音效 |
| scene | 场景配置变更（灯光、Timeline、Prefab 布局、Cinemachine 等） | 调整 D1S 酒吧场景灯光参数 |
| yarn | Yarn 对话剧本变更 | 更新佩佩 Day2 对话分支 |
| perf | 性能优化 | 减少语言粒子系统 DrawCall |
| refactor | 代码重构（不改变外部行为） | 将状态机逻辑从 Update 迁移到协程 |
| style | 代码格式调整（空格、缩进、命名等，不影响逻辑） | 统一 MiniGame 目录下命名风格 |
| docs | 文档变更 | 补充 TimelineKit 使用说明 |
| build | 构建/打包/CI 相关 | 更新 WebGL 构建配置 |
| chore | 杂项（依赖更新、配置调整、.gitignore 等） | 升级 DOTween 到 1.2.7 |
| test | 测试相关 | 添加对象池单元测试 |

### 选择 type 的原则

- 一次提交只做一件事，选最能体现主要变更的 type
- 如果同时涉及代码和美术，按主要变更选择（如功能开发附带占位美术 → `feat`）
- `fix` 仅用于修复已有 Bug，功能调整用 `feat`
- 纯资源替换/更新用 `art` / `audio`，伴随代码改动的用 `feat` 或 `fix`

---

## Scope 作用域定义

Scope 标注本次提交影响的模块，帮助团队快速定位变更范围。

### 核心系统

| scope | 对应目录 | 说明 |
|-------|---------|------|
| dialog | Scripts/Dialog System/ | 对话系统（Yarn Spinner 集成） |
| clue | Scripts/Clue/ | 线索/证据收集系统 |
| ui | Scripts/UI/ | 用户界面（Panel、DialogUI、Form） |
| scene-mgmt | Scripts/SceneManagement/ | 场景管理与切换 |
| fix-system | Scripts/FixSystem/ | 修复/拼图交互系统 |

### 小游戏

| scope | 对应目录 | 说明 |
|-------|---------|------|
| huoshan | Scripts/MiniGame/HuoShan/ | 火山系统（语言粒子、波形、情绪迷宫、分析模式） |
| blockpuzzle | Scripts/MiniGame/BlockPuzzle/ | 方块拼图 |
| peipei | Scripts/MiniGame/Peipei/ | 佩佩角色相关小游戏 |
| gear | Scripts/MiniGame/Gear/ | 齿轮系统 |

### 框架

| scope | 对应目录 | 说明 |
|-------|---------|------|
| action-kit | Scripts/Framework/ActionKit/ | 动作序列/命令模式 |
| audio-kit | Scripts/Framework/AudioKit/ | 音频管理 |
| pool-kit | Scripts/Framework/PoolKit/ | 对象池 |
| event-kit | Scripts/Framework/EventSystemKit/ | 事件系统 |
| timeline-kit | Scripts/Framework/TimelineKit/ | Timeline 管理 |
| state-machine | Scripts/Framework/StateMachineKit/ | 状态机 |
| resource-kit | Scripts/Framework/ResourceKit/ | 资源加载 |
| singleton-kit | Scripts/Framework/SingletonKit/ | 单例基类 |

### 其他

| scope | 说明 |
|-------|------|
| prototype | Web 原型（prototype/、web-prototype/） |
| config | 游戏配置、ProjectSettings |
| localization | 本地化/多语言 |
| save | 存档系统 |

**注意**：如果变更涉及多个模块或全局性改动，可以省略 scope。

---

## 分支命名规范

```
<type>/<简短英文描述>
```

### 分支类型

| 前缀 | 用途 | 示例 |
|------|------|------|
| feature/ | 新功能开发 | feature/block-puzzle-rotation |
| bugfix/ | Bug 修复 | bugfix/dialog-skip-crash |
| art/ | 美术资源批量更新 | art/huoshan-head-replace |
| hotfix/ | 紧急线上修复 | hotfix/save-data-corruption |
| release/ | 版本发布 | release/v0.3.0 |
| build/ | 打包/构建专用 | build/webgl-optimization |
| experiment/ | 实验性探索 | experiment/new-particle-system |

### 分支命名要求

- 使用英文小写 + 短横线（kebab-case）
- 简洁明确，2-5 个单词
- 避免使用中文（防止编码问题和跨平台兼容性问题）
- 避免使用日期作为分支名（如 ~~火山制作8.7~~）

### 长期分支

| 分支 | 用途 |
|------|------|
| master | 稳定发布版本 |
| develop | 开发主线，所有 feature 分支的合入目标 |
| playtest | 测试/试玩版本 |

---

## 完整示例

### 基本提交

```
feat(blockpuzzle): 添加方块旋转功能
```

### 带 body 的提交

```
fix(huoshan): 修复语言粒子碰撞后不消失的问题

粒子在碰撞检测回调中未正确归还对象池，
导致粒子数量持续增长引发帧率下降。
```

### 带 footer 的提交

```
feat(dialog): 支持对话中插入表情动画

在 Yarn 指令中新增 <<expression>> 命令，
可在对话气泡旁播放角色表情动画。

Closes #42
```

### 美术资源提交

```
art(huoshan): 替换火山头部高清模型和贴图
```

### 场景配置提交

```
scene(huoshan): 调整 HuoShanFixScene 灯光和后处理参数
```

### 多模块/全局变更（省略 scope）

```
chore: 升级 Unity 到 2022.3.20f1
```

### WIP 提交（临时保存，合并前需 squash）

```
chore: WIP 火山情绪模块原型开发中
```

---

## 对照改进表

以下是项目历史提交的改写示例，便于理解规范的实际效果：

| 原始提交 | 规范写法 |
|---------|---------|
| 提交 | feat(huoshan): 添加石头维修交互逻辑 |
| bugfix | fix(dialog): 修复对话跳过时崩溃的问题 |
| 美术资源替换 | art(huoshan): 替换火山头部模型和贴图 |
| 细碎的完善 | fix(ui): 修复设置面板滑块响应区域偏移 |
| 临时提交一下 | chore: WIP 火山情绪模块原型 |
| 更新 | feat(clue): 添加线索收藏功能 |
| 石头手感调整 | feat(huoshan): 优化石头拖拽手感和物理反馈 |
| 问题修复 | fix(scene-mgmt): 修复场景切换时音频未停止的问题 |
| 短按改长按 | feat(ui): 将确认按钮交互从短按改为长按 |
| text adj | yarn(dialog): 调整 D1S 对话文本措辞 |

---

## 常见问题

### Q: subject 用中文还是英文？

用**中文**。本项目团队以中文为主要工作语言，中文 subject 可以更准确、更快地传达变更内容。`type` 和 `scope` 保持英文以兼容工具链。

### Q: 提交粒度怎么把握？

- 一次提交只做一件事（One commit, one purpose）
- 避免在一个提交中混合功能开发、Bug 修复和资源替换
- 如果改动过大，考虑拆分为多个提交

### Q: 什么时候可以用 WIP 提交？

- 仅在需要临时保存进度时使用
- 合并到 develop 之前，必须用 `git rebase -i` 将 WIP 提交 squash 为有意义的提交

### Q: Merge Commit 消息怎么写？

使用默认的 merge commit 消息即可（如 `Merge branch 'feature/xxx' into 'develop'`），无需修改。

### Q: Unity 场景文件（.unity）和 Prefab 变更归哪个 type？

- 纯场景配置调整（灯光、摄像机、布局） → `scene`
- 添加新 Prefab / 新功能对象到场景 → `feat`
- 替换场景中的美术资源 → `art`