251 lines
7.9 KiB
Markdown
251 lines
7.9 KiB
Markdown
# 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`
|