From 4ebc5c16028b0aa38b7999074eea07f0fdd39f87 Mon Sep 17 00:00:00 2001 From: dev-team Date: Fri, 23 Oct 2026 09:18:41 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=A2=E9=98=9F=E5=8D=8F=E4=BD=9C?= =?UTF-8?q?=E8=A7=84=E8=8C=83=EF=BC=88=E5=88=86=E6=94=AF=E7=AD=96=E7=95=A5?= =?UTF-8?q?/=E5=88=86=E5=B7=A5/=E5=90=88=E5=B9=B6=E8=A7=84=E5=88=99?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Git协作规范.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 Git协作规范.md diff --git a/Git协作规范.md b/Git协作规范.md new file mode 100644 index 0000000..1ae0ae2 --- /dev/null +++ b/Git协作规范.md @@ -0,0 +1,83 @@ +# Git 协作规范（2-3 人团队） + +## 一、分支管理策略：main + feature 短分支 + +``` +main ──────●──────●────────●──→ 始终可编译可运行 + \ / \ / +feature/h264 ●── \ / +feature/linux-agent ─●── +``` + +| 分支 | 用途 | 生命周期 | +|---|---|---| +| `main` | 唯一稳定分支，随时可构建交付 | 永久，受保护 | +| `feature/<模块>-<内容>` | 一个功能一个分支 | ≤1 周，完成即合入删除 | + +规则（2-3 人小团队，够用且不添乱）： + +1. **main 受保护**：禁止直接 push，一律走 PR/MR 合入（哪怕自己合自己，留个审查记录）； +2. **feature 分支从最新 main 切出**：`git switch -c feature/agent-nvenc main`； +3. **小步提交 + 每天至少 rebase 一次 main**，避免长分支大冲突； +4. **协议（common/）改动**必须先合入，其他分支跟随——协议是三端共享契约； +5. 发版时打 tag：`git tag v0.2.0 && git push --tags`。 + +### 常用命令速查 + +```bash +git switch -c feature/agent-nvenc main # 切新分支 +git add -p && git commit -m "feat(agent): ..." # 交互式暂存提交 +git fetch && git rebase origin/main # 同步 main +git push -u origin feature/agent-nvenc # 推送并建立跟踪 +``` + +### 提交信息格式 + +``` +<类型>(<模块>): <一句话说明> + +类型：feat / fix / refactor / docs / perf / chore +模块：agent / viewer / common / build +示例：perf(agent): 采集限速 30fps 降低带宽需求 +``` + +## 二、模块分工建议（按当前代码结构） + +代码分三个 crate，边界清晰，天然适合按模块认领： + +| 成员 | 主责模块 | 内容 | +|---|---|---| +| **A** | `agent/`（被控端） | DXGI 采集、openh264 编码调优 → NVENC 硬编、关键帧策略、Windows 服务化、后续 **Linux 被控端**（新 crate `linux-agent/`） | +| **B** | `viewer/`（主控端） | 渲染/HUD、键鼠映射、手机端主控（后期）、多屏支持 | +| **C** | `common/` + 传输/服务端 | 协议设计（serde 消息）、QUIC 调优、P2P 打洞 + coturn、信令服务器、码率自适应 | + +> 2 人时：A 管 agent 侧，B 管 viewer+common，传输/服务端按阶段共同承担。 + +## 三、协作流程（一个功能的完整生命周期） + +``` +1. 领任务 → 在 issue/任务清单认领，切 feature 分支 +2. 开发 → 小步提交（一事一提交） +3. 自测 → cargo build --release 通过 + 回环冒烟测试 +4. 提 PR → 描述改动 + 测试方法，指定另一人 review +5. Review → 至少 1 人批准；协议改动需全员看过 +6. 合入 → squash merge 进 main，删 feature 分支 +7. 联调 → main 上跑双机测试，通过后打 tag +``` + +## 四、代码合并规范 + +1. **合并方式**：统一 squash merge（`git merge --squash` 或平台按钮），main 历史保持一功能一提交； +2. **冲突处理**：谁的功能分支谁 rebase，禁止在 main 上直接改冲突； +3. **必须过审的改动**： + - `common/` 任何改动（协议兼容性，三端都受影响） + - 加密/认证相关代码 + - `Cargo.toml` 新增依赖（确认许可证 + 维护活跃度） +4. **不合并的代码**：编译不过的不合、回环冒烟不过的不合、带 `dbg!`/注释代码块的不合； +5. **Cargo.lock 提交入库**（已提交），依赖变更必须连 lock 一起提。 + +## 五、当前仓库注意事项 + +- `target/`（1.4G）、`*.exe`、`*.dll` 已在 .gitignore 排除；**构建产物不入库**，部署用 exe 各自按《构建运行手册.md》编译，或后续用 GitHub Releases/内部网盘分发； +- mingw 运行库 3 个 DLL（libstdc++-6 等）不入库，发布时手动附带； +- 本仓库当前为本地仓库，需要远端托管时：`git remote add origin && git push -u origin main`。