From 710cd45a48f47cb2ea80af00ca905c6a153303e7 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Sun, 31 May 2026 01:56:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20UE5.7=20=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=20Git=20=E9=85=8D=E7=BD=AE=E4=B8=8E=E5=BC=80=E5=8F=91?= =?UTF-8?q?=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 优化 .gitignore 为 UE5.7 专用版本（新增 Rider/VSCode/日志/崩溃/系统文件等） - 添加 .gitattributes 配置二进制资产处理与 Git LFS 追踪 - 添加 docs/GIT-GUIDE.md 分支策略与提交规范文档 - 添加 .claude/settings.json 项目级权限配置 Co-Authored-By: Claude Opus 4.8 --- .claude/settings.json | 12 +++ .gitattributes | 69 +++++++++++++ .gitignore | 147 +++++++++++++++----------- docs/GIT-GUIDE.md | 233 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 399 insertions(+), 62 deletions(-) create mode 100644 .claude/settings.json create mode 100644 .gitattributes create mode 100644 docs/GIT-GUIDE.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..bdfcbdc --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,12 @@ +{ + "permissions": { + "allow": [ + "Bash(dir:*)", + "Bash(git:*)", + "mcp__web-reader__webReader", + "mcp__zread__get_repo_structure", + "mcp__web-search-prime__webSearchPrime", + "WebSearch" + ] + } +} diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..347a563 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,69 @@ +# UE5 Git Attributes - ChildHood Project + +# ============================== +# 二进制资产（禁止文本合并，避免损坏） +# ============================== +*.uasset binary +*.umap binary + +# ============================== +# Git LFS 大文件追踪 +# ============================== +*.uasset filter=lfs diff=lfs merge=lfs -text +*.umap filter=lfs diff=lfs merge=lfs -text + +# ============================== +# 美术资源 +# ============================== +*.png filter=lfs diff=lfs merge=lfs -text +*.jpg filter=lfs diff=lfs merge=lfs -text +*.jpeg filter=lfs diff=lfs merge=lfs -text +*.tga filter=lfs diff=lfs merge=lfs -text +*.bmp filter=lfs diff=lfs merge=lfs -text +*.psd filter=lfs diff=lfs merge=lfs -text +*.ai filter=lfs diff=lfs merge=lfs -text + +# ============================== +# 3D 模型 +# ============================== +*.fbx filter=lfs diff=lfs merge=lfs -text +*.obj filter=lfs diff=lfs merge=lfs -text +*.gltf filter=lfs diff=lfs merge=lfs -text +*.glb filter=lfs diff=lfs merge=lfs -text + +# ============================== +# 音频 +# ============================== +*.wav filter=lfs diff=lfs merge=lfs -text +*.mp3 filter=lfs diff=lfs merge=lfs -text +*.ogg filter=lfs diff=lfs merge=lfs -text +*.flac filter=lfs diff=lfs merge=lfs -text + +# ============================== +# 视频 +# ============================== +*.mp4 filter=lfs diff=lfs merge=lfs -text +*.avi filter=lfs diff=lfs merge=lfs -text +*.mov filter=lfs diff=lfs merge=lfs -text +*.wmv filter=lfs diff=lfs merge=lfs -text + +# ============================== +# 文本 / 代码（正常 diff） +# ============================== +*.cpp text +*.h text +*.cs text +*.json text +*.ini text +*.cfg text +*.md text +*.txt text +*.uproject text +*.uplugin text +*.Build.cs text +*.Target.cs text + +# ============================== +# 自动换行（Windows 开发环境） +# ============================== +* text=auto diff --git a/.gitignore b/.gitignore index 715b38f..b6e192a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,40 +1,11 @@ -# ---> UnrealEngine -# Visual Studio 2015 user specific files +# ============================== +# ChildHood - UE5.7 Git Ignore +# ============================== + +# ============================== +# Visual Studio +# ============================== .vs/ - -# Compiled Object files -*.slo -*.lo -*.o -*.obj - -# Precompiled Headers -*.gch -*.pch - -# Compiled Dynamic libraries -*.so -*.dylib -*.dll - -# Fortran module files -*.mod - -# Compiled Static libraries -*.lai -*.la -*.a -*.lib - -# Executables -*.exe -*.out -*.app -*.ipa - -# These project files can be generated by the engine -*.xcodeproj -*.xcworkspace *.sln *.suo *.opensdf @@ -42,35 +13,87 @@ *.VC.db *.VC.opendb -# Precompiled Assets +# ============================== +# JetBrains Rider +# ============================== +.idea/ +*.csproj +*.DotSettings.user + +# ============================== +# VS Code +# ============================== +.vscode/ + +# ============================== +# 编译产物 +# ============================== +*.o +*.obj +*.pch +*.gch +*.dll +*.so +*.dylib +*.lib +*.a +*.pdb +*.exe +*.out +*.ipa + +# ============================== +# UE5 引擎生成目录 +# ============================== +Binaries/ +Intermediate/ +DerivedDataCache/ +Saved/ +Build/ +Staging/ +Script/ + +# 插件内的编译产物 +Plugins/**/Binaries/ +Plugins/**/Intermediate/ + +# 保留 Build 中的图标和 PakBlacklist +!Build/**/*.ico +!Build/*/PakBlacklist*.txt + +# ============================== +# UE5 烘焙数据 +# ============================== +*_BuiltData.uasset + +# ============================== +# 预编译资源源文件 +# ============================== SourceArt/**/*.png SourceArt/**/*.tga -# Binary Files -Binaries/* -Plugins/**/Binaries/* +# ============================== +# 日志与崩溃报告 +# ============================== +*.log +CrashReportClient/ -# Builds -Build/* +# ============================== +# 系统文件 +# ============================== +.DS_Store +Thumbs.db +Desktop.ini +*.lnk -# Whitelist PakBlacklist-.txt files -!Build/*/ -Build/*/** -!Build/*/PakBlacklist*.txt - -# Don't ignore icon files in Build -!Build/**/*.ico - -# Built data for maps -*_BuiltData.uasset - -# Configuration files generated by the Editor -Saved/* - -# Compiled source files for the engine to use -Intermediate/* -Plugins/**/Intermediate/* - -# Cache files for the editor to use -DerivedDataCache/* +# ============================== +# Git LFS 临时文件 +# ============================== +*.lfs +# ============================== +# 其他 +# ============================== +*.swp +*.swo +*~ diff --git a/docs/GIT-GUIDE.md b/docs/GIT-GUIDE.md new file mode 100644 index 0000000..55a3a9e --- /dev/null +++ b/docs/GIT-GUIDE.md @@ -0,0 +1,233 @@ +# 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 提交消息格式 + +``` +(): + +（可选，多行说明） +``` + +- **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 提交示例 + +```bash +# 新功能 +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 修复、小调整 + +--- + +## 四、常用命令速查 + +```bash +# 查看当前状态 +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 +```