docs: add worktree lifecycle and cleanup rules

Feature work happens in D:/OPC/synapbus-wt/issue-<N>; after the branch
is merged into opc/main (and the running binary replaced if needed) the
implementing agent removes the worktree with git worktree remove, after
restoring the skip-worktree go.mod/go.sum patch. Never --force, never
delete branches, never remove unmerged or dirty worktrees.

OPC local patch (opc/main only).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
QiuSW
2026-10-06 14:21:44 +08:00
co-authored by Claude Opus 5.5
parent 92a2e034c0
commit 198b043186
+8
View File
@@ -11,6 +11,14 @@
- 本地专用、不打算提给上游的补丁(如 Windows 编译修复)直接提交到 `opc/main`,并在提交信息中注明 `OPC local patch`。
- 同步上游后把 `main` 合入 `opc/main`,重新编译并跑测试,确认本地补丁仍然需要、仍然有效。
### worktree 使用与清理
- 功能分支在独立 worktree 中开发,统一放在 `D:/OPC/synapbus-wt/issue-<N>`;`D:/OPC/synapbus` 是正在运行服务的检出,不在其中切分支开发。
- Windows 编译补丁(renameio)在功能 worktree 中以未提交 + `skip-worktree` 的方式放置,不提交到功能分支。
- 功能分支合入 `opc/main` 并推送后(需要替换运行中二进制的,在替换完成后),由实施该工单的 Agent 删除对应 worktree,并在工单记录。删除前确认:HEAD 已合入 `opc/main`;除 skip-worktree 文件外 `git status --porcelain` 为空;没有进程引用;目录内指向外部的链接先断开。
- 删除前先撤销 skip-worktree 标记并还原 `go.mod`/`go.sum`(`git update-index --no-skip-worktree go.mod go.sum` 后 `git checkout -- go.mod go.sum`),再执行 `git worktree remove <路径>`,不加 `--force`,不删除分支;之后 `git worktree prune`。
- 未合并或有未提交改动的 worktree 不得删除,先向用户报告。
## 2. 工单
- 功能、缺陷修复,以及鉴权、权限、接口、数据库迁移方面的改动,先在 Gitea `OPC/synapbus` 建工单,写清目标、非目标、方案、验收、风险和测试;方案经用户确认后再写代码。