diff --git a/CLAUDE.md b/CLAUDE.md index 83d5350b7..0880b6834 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -124,6 +124,7 @@ Located in `Assets/Resources/Yarn/`, organized by character and day: ### Git Configuration - **LFS**: Used for large binary assets (.unity, textures, audio) - **Ignored**: Library/, Temp/, Logs/, Build/, *.csproj.user +- **Commit Convention**: See [COMMIT_CONVENTION.md](COMMIT_CONVENTION.md) for commit message format and branch naming rules. All commits must follow `(): ` format. ## Testing and Iteration diff --git a/COMMIT_CONVENTION.md b/COMMIT_CONVENTION.md new file mode 100644 index 000000000..6fcbb4954 --- /dev/null +++ b/COMMIT_CONVENTION.md @@ -0,0 +1,250 @@ +# Git 提交规范 + +本文档定义 AIBIS Dream 项目的 Git 提交消息格式、分支命名规范与最佳实践。 + +--- + +## 提交消息格式 + +采用 [Conventional Commits](https://www.conventionalcommits.org/) 规范，结构如下： + +``` +(): + +[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。 + +--- + +## 分支命名规范 + +``` +/<简短英文描述> +``` + +### 分支类型 + +| 前缀 | 用途 | 示例 | +|------|------|------| +| 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 指令中新增 <> 命令， +可在对话气泡旁播放角色表情动画。 + +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`