ChildHood/docs/GIT-GUIDE.md

ChildHood - Git 规范

本文档规定 ChildHood 项目的 Git 分支策略和提交规范。 适用场景：单人独立开发 + UE5.7.4

---

一、分支策略

采用轻量级 Feature Branch 模型，避免企业级复杂流程，保持 main 分支随时可玩。

1.1 分支总览

main ──────────────────────────────────────── 稳定主线
 │
 ├── feature/player-movement ───→ 合并后删除
 ├── feature/inventory-system ──→ 合并后删除
 ├── fix/camera-clipping ───────→ 合并后删除
 ├── prototype/procedural-gen ──→ 实验完即删
 └── release/v0.1 ──────────────→ 永久保留

1.2 分支类型

分支	前缀	用途	合并目标	生命周期
主线	main	稳定可玩版本，每次提交都能编译运行	—	永久
功能	feature/	新系统、新功能开发	main	完成后删除
修复	fix/	Bug 修复	main	完成后删除
原型	prototype/	技术验证、玩法实验	合并或丢弃	实验完即删
发布	release/	版本发布标记，只从 main 切出	—	永久保留

1.3 命名规范

格式：<类型>/<简短描述>，全小写，用连字符分隔单词。

# ✅ 好的命名
feature/player-movement
feature/inventory-system
feature/dialogue-tree
fix/camera-clipping-through-walls
fix/enemy-ai-stuck-on-navmesh
prototype/procedural-dungeon
release/v0.1

# ❌ 不好的命名
my-new-feature
fix-bug
test
feature/AddPlayerMovement

1.4 工作流程

1. 开始新功能
   git checkout main
   git pull
   git checkout -b feature/xxx

2. 开发过程中（随时提交）
   git add .
   git commit -m "wip(xxx): 进度描述"

3. 功能完成，测试通过
   git checkout main
   git merge feature/xxx
   git branch -d feature/xxx        # 删除已合并分支

4. 到达里程碑
   git checkout main
   git tag -a v0.1.0 -m "第一个可玩原型"
   git checkout -b release/v0.1
   git push origin release/v0.1

1.5 核心原则

• main 永远可玩：坏了就留在 feature 分支继续改，不要合并进 main
• 功能分支粒度：一个分支做一件事，不要在一个分支里同时做多个系统
• 原型不怕乱：prototype/ 分支随便写，验证完再决定合并还是丢弃
• 定期清理：已合并的 feature/fix 分支及时删除，避免分支堆积

---

二、提交规范

2.1 提交消息格式

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

<body>（可选，多行说明）

• subject：不超过 50 个字符，简明扼要
• body：每行不超过 72 个字符，解释"做了什么"和"为什么"
• 使用中文描述，技术术语保留英文

2.2 Type 类型标签

Type	含义	使用场景
feat	新功能	新增系统、机制、玩法
fix	Bug 修复	修复已知问题
art	美术资源	模型、贴图、材质、动画导入
level	关卡/场景	关卡搭建、场景编辑
audio	音效/音乐	BGM、SFX、语音导入
bp	蓝图逻辑	蓝图节点修改、逻辑调整
refactor	重构	不改变功能的结构优化
config	项目配置	引擎设置、插件配置、项目参数
docs	文档	README、设计文档、注释
wip	进行中	未完成的工作进度保存

2.3 Scope 范围标签（可选）

按游戏系统或模块划分：

player      玩家角色
enemy       敌人/AI
combat      战斗系统
ui          UI 界面
camera      摄像机
inventory   背包/物品
dialogue    对话系统
quest       任务系统
save        存档系统
audio       音频系统
animation   动画系统
ai          AI 行为树/状态机
level       关卡
vfx         视觉特效

2.4 提交示例

# 新功能
git commit -m "feat(player): 实现角色跳跃和二段跳"

# 带 body 的详细提交
git commit -m "feat(combat): 实现基础连击系统

- 添加三段连击动画蒙太奇
- 实现动画通知触发伤害判定
- 连击窗口时间可配置"

# Bug 修复
git commit -m "fix(camera): 修复穿墙时摄像机卡顿问题"

# 美术资源
git commit -m "art(environment): 添加草地和树木模型"

# 蓝图修改
git commit -m "bp(enemy): 实现巡逻-追击-攻击状态机"

# 关卡搭建
git commit -m "level(chapter1): 第一章关卡白盒搭建完成"

# 进行中
git commit -m "wip(crafting): 合成系统UI初步框架"

# 项目配置
git commit -m "config: 启用Nanite和Lumen，设置画质预设"

# 重构
git commit -m "refactor(inventory): 拆分背包数据层与UI层"

2.5 提交粒度建议

操作	粒度
蓝图逻辑	按功能点提交，不要一次提交多个系统
关卡编辑	按区域/房间提交
美术资源导入	按类型/角色分批提交
C++ 代码	按逻辑单元提交
材质/贴图	按材质组提交

2.6 UE5 特别注意

• 蓝图与 C++ 分开提交：避免同一提交中混合两者，方便出问题时 revert
• 二进制文件提交：.uasset、.umap 无法 diff，commit message 要写清楚改了什么
• 不要提交以下目录（已被 .gitignore 排除）：
  • Binaries/、Intermediate/、Saved/、DerivedDataCache/
  • .vs/、*.sln（由引擎自动生成）

---

三、版本号规范

采用简化语义化版本：

v主版本.次版本.修订号

v0.1.0  ← 第一个可玩原型
v0.2.0  ← 核心玩法成型
v0.3.0  ← 内容填充阶段
...
v1.0.0  ← 正式发布

• 主版本：重大里程碑（原型、Alpha、正式版）
• 次版本：新系统/大功能完成
• 修订号：Bug 修复、小调整

---

四、常用命令速查

# 查看当前状态
git status
git log --oneline --graph --all

# 开始新功能
git checkout -b feature/xxx

# 暂存当前工作（需要临时切分支时）
git stash
git stash pop

# 撤销上次提交（保留修改）
git reset --soft HEAD~1

# 强制同步远程（仅限个人项目）
git fetch origin
git reset --hard origin/main