diff --git a/DOWNSTREAM.md b/DOWNSTREAM.md new file mode 100644 index 0000000..a2925de --- /dev/null +++ b/DOWNSTREAM.md @@ -0,0 +1,38 @@ +# OpenMAIC 二次开发 Git 约定 + +本仓库基于 [THU-MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC),保留上游的完整 Git 历史。首次导入基线为 `29735f1`。 + +## 仓库与分支 + +- `origin`:本 Gitea 仓库,是二次开发代码和评审的归宿。 +- `upstream`:原始 GitHub 仓库,只用于获取上游更新;不要向它推送二次开发代码。 +- `main`:已集成、可工作的二次开发主线。功能和修复先在独立分支完成,经评审后合入。 +- 功能分支:从最新的 `main` 创建,例如 `feat/course-export`、`fix/slide-layout`。一个分支只处理一项改动。 + +## 日常开发 + +```bash +git switch main +git pull --ff-only origin main +git switch -c feat/ +# 完成并提交改动后 +git push -u origin feat/ +``` + +在 Gitea 中为功能分支创建合并请求,检查构建与测试后合入 `main`。不要把本地未提交文件直接带进其他分支的提交。 + +## 同步上游 + +定期把上游更新合入主线。使用 merge 保留上游提交和本地改动的共同历史,便于追踪冲突来源。 + +```bash +git fetch upstream +git switch main +git pull --ff-only origin main +git switch -c chore/sync-upstream- +git merge --no-ff upstream/main +# 解决冲突,运行相关检查,再推送并创建合并请求 +git push -u origin chore/sync-upstream- +``` + +如果上游发布稳定版本,也可以在同步分支上合入对应 tag,并在合并请求中记录版本号。避免重写已共享的 `main` 历史;不要对它执行强制推送。