docs: document downstream Git workflow
Some checks failed
CI / Lint, Typecheck & Unit Tests (push) Has been cancelled
CI / Render Service (typecheck + tests) (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
Storage PostgreSQL Contract / Storage Contract (PostgreSQL 16) (push) Has been cancelled

This commit is contained in:
yue02.sun 2026-09-22 11:29:58 +08:00
parent 29735f10d0
commit e61957fd4d

38
DOWNSTREAM.md Normal file
View File

@ -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/<topic>
# 完成并提交改动后
git push -u origin feat/<topic>
```
在 Gitea 中为功能分支创建合并请求,检查构建与测试后合入 `main`。不要把本地未提交文件直接带进其他分支的提交。
## 同步上游
定期把上游更新合入主线。使用 merge 保留上游提交和本地改动的共同历史,便于追踪冲突来源。
```bash
git fetch upstream
git switch main
git pull --ff-only origin main
git switch -c chore/sync-upstream-<date>
git merge --no-ff upstream/main
# 解决冲突,运行相关检查,再推送并创建合并请求
git push -u origin chore/sync-upstream-<date>
```
如果上游发布稳定版本,也可以在同步分支上合入对应 tag,并在合并请求中记录版本号。避免重写已共享的 `main` 历史;不要对它执行强制推送。