docs: 添加提交规范并更新仓库协作说明

Made-with: Cursor
2026-02-28 15:55:44 +08:00
parent 19c290091e
commit f8394fd59d
2 changed files with 251 additions and 0 deletions
@@ -0,0 +1,250 @@
+# 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`