新增协作规范文档 CONTRIBUTING.md

2026-08-05 15:25:11 +08:00
@@ -0,0 +1,112 @@
+# 协作规范（Collaboration Guide）
+
+本文件是 Marry 项目的 Git 协作守则。**两人协作前请先读完**，遇到问题时对照这里的场景处理。
+
+## 一、首次克隆项目
+
+```bash
+git clone https://git.onxiou.cn/ProMax-Marry/Marry.git
+cd Marry
+git submodule update --init   # 拉取 C++ 绑定库 godot-cpp
+```
+
+> 为什么有第三条：godot-cpp 是子模块（仓库里只存指针，不存源码）。
+> clone 后必须执行 `git submodule update --init` 才能拿到真正的绑定库，否则 C++ 编译会失败。
+> 如果这条偶发报错（网络问题），重跑一遍即可。
+
+## 二、日常开发流程（每天必做）
+
+```
+开工前：  git pull                # 拉取对方最新代码
+写代码：  修改文件...
+提交：    git add .               # 暂存所有改动
+          git commit -m "说明"    # 提交到本地
+推送：    git push                # 上传到服务器
+```
+
+按这个顺序，每次提交前先 `git pull`，可以避免 90% 的冲突。
+
+## 三、推送被拒绝时（最常见场景）
+
+**现象：** `git push` 报错 `non-fast-forward` 或 `fetch first`。
+
+**原因：** 对方先推送了新提交，你的本地历史落后了。
+
+**处理：** 不要慌，按顺序执行：
+
+```bash
+git pull --rebase     # 把你的提交"挪"到对方最新提交之上
+git push              # 再推送
+```
+
+> 为什么用 `--rebase` 而不是直接 `git pull`：
+> 普通 pull 会产生一个多余的 "Merge branch" 合并提交，历史变成网状；
+> `--rebase` 让历史保持一条直线，清爽且不易混乱。
+
+## 四、关于分叉（diverging branches）
+
+**现象：** `git pull` 提示 `Diverging branches can't be fast-forwarded`。
+
+**原因：** 本地和服务器都有对方没有的提交，两边分开了。
+
+**两种分叉的处理完全不同：**
+
+### 1. 正常协作分叉（会经常遇到，无害）
+按第三节处理：`git pull --rebase` → `git push`，完成。
+
+### 2. 历史重写分叉（异常情况，需要统一处理）
+当有人改了历史并强制推送（force push）后，其他人的本地历史与服务器对不上。
+**处理方式：** 确认自己本地没有未推送的独特提交后：
+
+```bash
+git status                        # 先看有没有未提交改动
+git fetch origin
+git reset --hard origin/main      # 丢弃旧历史，对齐服务器
+git submodule update --init       # 重新拉子模块
+```
+
+## 五、铁律（违反会坑队友）
+
+1. **永远不要 `git push --force`**
+   强制推送会覆盖服务器历史，所有已 clone 的人都会分叉。
+   除非要清理误提交（如密码泄露），且**先通知所有人**再操作。
+
+2. **提交推上服务器后，不要 reset / rebase / amend 改它**
+   改已推送的历史 = 制造分叉。
+
+3. **两人不要同时改同一个文件**
+   分工时尽量各管各的场景/模块。Godot 的 .tscn 场景文件合并很容易冲突。
+
+## 六、哪些文件不该提交（.gitignore 已配置）
+
+- `.godot/` — Godot 编辑器缓存（每次打开都会变，提交了必冲突）
+- `bin/`、`build/` — C++ 编译产物
+- `*.user`、`.vs/` — IDE 个人配置
+
+> 如果你 `git status` 看到这些文件，说明 .gitignore 没生效或被强制添加了，
+> 不要提交它们，告诉我处理。
+
+## 七、环境要求
+
+| 工具 | 版本 | 用途 |
+|------|------|------|
+| Godot | 4.6（标准版） | 游戏引擎，打开 main/project.godot |
+| Visual Studio | 2026+（含 C++ 工具集） | 编写/编译 C++ 扩展 |
+| Git | 任意 | 版本控制 |
+| Python | 3.12（E:\Python312） | godot-cpp 编译依赖 |
+
+## 八、C++ 扩展编译
+
+```bash
+# Windows 命令行
+build-marry.bat
+
+# 或 Visual Studio
+# 打开 CMakeLists.txt → 生成 → 编译
+```
+
+编译产物输出到 `bin/marry.dll`，Godot 通过 `marry.gdextension` 自动加载。
+
+---
+
+遇到文档没覆盖的情况，先 `git pull`，再对照场景处理；拿不准就问对方/管理员，不要乱执行 force 相关命令。