From 03811b3806e7ab81b612706adae7861f643e12d8 Mon Sep 17 00:00:00 2001 From: KnowSky404 Date: Mon, 26 Oct 2026 15:57:12 +0800 Subject: [PATCH] docs(workflow): adopt worktree and reviewed rebase delivery --- .github/pull_request_template.md | 42 ++++++++++ AGENTS.md | 90 ++++++++++++++++++++- README.md | 4 + README.zh-CN.md | 3 + docs/wiki/Changelog.md | 9 +++ docs/wiki/Changelog.zh-CN.md | 8 ++ docs/wiki/Development.md | 131 +++++++++++++++++++++++++++++++ docs/wiki/Development.zh-CN.md | 99 +++++++++++++++++++++++ 8 files changed, 385 insertions(+), 1 deletion(-) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..092bf28 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,42 @@ +## Problem and resulting behavior + + + +## Task and verification evidence + +- Worktree / branch: +- Base SHA / tested head SHA: +- Local checks and results: +- CI results for this head: +- Screenshots for UI changes: +- Missing prerequisites, skipped checks, and remaining limitations: + + + +## Review gate (update before merge) + +- [ ] Codex Code Review completed for the current head; author and SHA verified. +- [ ] Security Review and other required reviews completed when enabled; + actual repository configuration checked. +- [ ] Review SHA, completion times, and evidence links recorded below. +- [ ] Valid blocking findings resolved; false positives explained with evidence. +- [ ] Required CI checks passed for the current head; new commits reviewed again. + +Review evidence: + +## Merge and completion (update after authorized merge) + + + +- Merge authorization / PR URL / original head / merge SHA: +- Main integration and sync evidence: +- Worktree and local/remote branch cleanup, retention, or blockers: diff --git a/AGENTS.md b/AGENTS.md index 8f2e222..b24cd70 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,91 @@ # Codex Context - SubMan +## Default Development Workflow + +Use this workflow for every feature, fix, refactor, test, configuration, and +documentation change, including small updates: + +**Dedicated local worktree + task branch -> local implementation and verification +-> atomic commit -> push and PR -> completed review and resolved findings +-> rebase merge into `main` -> verify and sync main -> remove the merged task +worktree and local/remote branches.** + +- Before editing, inspect cwd, branch, upstream, working tree, and + `git worktree list`. Fetch and verify the latest `origin/main`, then create a + dedicated worktree and new `feat/`, `fix/`, or `docs/` + branch. Resume an existing task in its own worktree/branch. Do not develop on + `main` or switch the user's original checkout to the task branch. +- Place worktrees outside the repository, in a sibling or writable temporary + directory. Record the absolute path, branch, and base SHA. Isolate dependencies, + generated output, local Worker/DO state, browser state, and server ports. Do not + share writable build directories or automatically copy private configs/tokens. +- Preserve unrelated changes. Do not reset, stash, rebase, force-push, or delete + another task's work. Keep unmerged worktrees and branches for continuation. +- Validate locally and create an atomic Conventional Commit before any authorized + push/PR. Target PRs at `main`; include the problem, resulting behavior, base and + tested SHAs, validation evidence, and limitations. Use a temporary body file + with `--body-file` for multiline GitHub CLI descriptions. +- After opening a PR or updating its head, actively check Codex bot review. + Every PR, including documentation, requires completed Code Review of the + current head and resolution of valid blocking findings. Verify the actual bot + author (`chatgpt-codex-connector[bot]`, sometimes displayed without `[bot]`), + reviewed SHA, completion evidence, and inline findings. Also require Security + Review and any other configured required reviews when enabled; verify actual + repository configuration rather than assuming FlareMail's settings apply. +- Check each review item and its commit in `Codex Review Summary` and associated + reviews/comments. A single summary status/head SHA, `COMMENTED`, a reaction, + `CLEAN` mergeability, empty Actions checks, or an older review does not prove + completion. Review not appearing yet does not prove it is disabled. New commits + require new review and affected checks. Record review SHA, completion time, and + links; explain false positives with evidence. If review is pending, failed, or + cannot be verified, retain the PR/branch/worktree and report the blocker. Do not + bypass review by waiting out a timeout or enabling auto-merge early. +- Push, PR creation, merge, direct pushes to `main`, Wiki publication, and + deployment require authorization covering those actions. This workflow defines + order, not additional authorization; do not ask again for an already authorized + action within the same scope. Ordinary development does not authorize remote + publication or production deployment. SubMan keeps its existing CI and local + checks; FlareMail's PRE requirement is not a SubMan gate. + +### Rebase Merge and Cleanup + +1. Before an authorized merge, verify the target `main`, PR head, commits/files, + mergeability, required checks, and completed current-head reviews. Default to + `gh pr merge --rebase --match-head-commit ` unless the + user specifies another strategy. Do not use `--admin` to bypass gates. A queue + or auto-merge request is not a completed merge; wait for actual `MERGED` state. +2. Record PR URL, original head, and merge SHA. Fetch `origin/main` and verify it + contains the merge SHA and all task changes. Rebase rewrites commit identities; + use the PR merge record plus patch/content comparison, such as `git range-diff` + of the original and rebased ranges. Original-head ancestry alone is inadequate. + Repeat affected checks when conflict resolution or integration changes content. +3. Sync the original checkout with `git merge --ff-only origin/main` only if it + is on `main`, clean, and can fast-forward. Preserve a dirty/diverged checkout + and report it without reset, stash, or automatic rebase. Independently safe + cleanup of a verified merged task may still proceed. +4. After a verified authorized merge, clean up this task by default unless the + user requests retention. Verify task branches still point to the merged PR + head with no new commits. Check staged, unstaged, untracked, and valuable + ignored files; preserve private configuration and validation evidence, and + stop temporary services. From a retained checkout, use + `git worktree remove ` without `--force`, then `git branch -d `. + Never remove the main checkout or another task's worktree. +5. Delete a remaining remote task branch only with an explicit lease pinned to + the verified merged PR head: + `git push --force-with-lease=refs/heads/: origin :refs/heads/`. + This permits conditional deletion, not history overwrites. Do not use + unconditional `--delete` or `--force`. If absent, record it; if the lease fails, + preserve the branch and report it without retrying against an unmerged head. +6. If local `-d` refuses only because rebase changed ancestry, `-D` is permitted + only after proving PR `MERGED`, merge SHA in main, unchanged task head, and + equivalent patches/content. A successful `-d` alone is not integration proof. + Unsaved files, unmerged commits, another worktree using the branch, or a user + retention request stop the affected cleanup. Report PR URL, final SHA, + validation, main sync, cleanup, and remaining blockers. Merge/cleanup do not + deploy production. + +Commands and examples: [development guide](docs/wiki/Development.md). + ## Product SubMan manages VLESS, VMess, and related proxy resources. The sole business @@ -215,7 +301,9 @@ green. Vite is for UI iteration; use `dev:cf` for Worker/DO runtime evidence. - Keep code identifiers and comments ASCII. - Add behavior tests before changing established protocol behavior. - Commit each independent feature, UI change, refactor, or bug fix immediately - with an atomic Conventional Commit. + after applicable verification with an atomic Conventional Commit in its task + worktree. Documentation-only changes require `bun run docs:check` plus diff, + command, and link review; runtime checks apply when implementation changes. - Keep README concise. Maintain detailed guides in the bilingual Wiki sources indexed by `docs/wiki/Home.md`; record changes in both `docs/wiki/Changelog.md` and `docs/wiki/Changelog.zh-CN.md`. Run `bun run docs:check` before committing. diff --git a/README.md b/README.md index 4d9de99..1984771 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,10 @@ See the [user guide](docs/wiki/User-Guide.md) for setup and recovery. ## Local development +Use a dedicated worktree and task branch for every change. PRs require current-head +review before an authorized rebase merge; verify main, then clean up merged task +branches and worktrees. Follow the [development workflow](docs/wiki/Development.md#worktree-and-pr-workflow). + Use Bun **1.3.14**: ```bash diff --git a/README.zh-CN.md b/README.zh-CN.md index c79eca0..e9174f6 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -31,6 +31,9 @@ Token 默认仅在当前会话保存,持久保存需主动选择。 ## 本地开发 +每项改动使用独立 worktree 和任务分支。PR 完成当前 head 的 review 后按授权 rebase 合并, +核对主分支后清理已合并任务的分支和 worktree,详见[开发流程](docs/wiki/Development.zh-CN.md#worktree-与-pr-工作流)。 + 使用 Bun **1.3.14**: ```bash diff --git a/docs/wiki/Changelog.md b/docs/wiki/Changelog.md index 531c505..5e24d1c 100644 --- a/docs/wiki/Changelog.md +++ b/docs/wiki/Changelog.md @@ -8,6 +8,15 @@ production deployment and real-provider acceptance require separate evidence. ## Unreleased +### 2026-10-26 - Worktree and PR development workflow + +- Adopted FlareMail's task isolation, current-head Codex review, rebase merge, + main verification/sync, and merged worktree/branch cleanup conventions. +- Added a PR template and bilingual workflow instructions, including conditional + remote branch deletion and rebase-aware integration checks. +- Kept SubMan's CI, Bun version, and publication/deployment authorization rules; + repository instructions do not configure GitHub review integrations or rulesets. + ### 2026-10-26 - API and sing-box-vps compatibility review - Clarified tiered Gist discovery and nonempty PATCH inputs in OpenAPI and the diff --git a/docs/wiki/Changelog.zh-CN.md b/docs/wiki/Changelog.zh-CN.md index ffa00c7..487cd6d 100644 --- a/docs/wiki/Changelog.zh-CN.md +++ b/docs/wiki/Changelog.zh-CN.md @@ -7,6 +7,14 @@ ## 未发布 +### 2026-10-26 - Worktree 与 PR 开发工作流 + +- 参考 FlareMail,统一任务隔离、当前 head 的 Codex review、rebase 合并、 + 主分支核对/同步及已合并 worktree/分支清理约定。 +- 增加 PR 模板和双语操作指南,明确远端分支条件删除与 rebase 后的整合核对。 +- 保留 SubMan 的 CI、Bun 版本和发布/部署授权规则; + 仓库约定不等于已配置 GitHub review 集成或 ruleset。 + ### 2026-10-26 - API 与 sing-box-vps 兼容性核对 - 在 OpenAPI 和中英文 API、Agent 参考中明确分层 Gist 发现策略与非空 PATCH 要求, diff --git a/docs/wiki/Development.md b/docs/wiki/Development.md index 6be6979..c2bbffc 100644 --- a/docs/wiki/Development.md +++ b/docs/wiki/Development.md @@ -2,6 +2,130 @@ English | [简体中文](Development.zh-CN.md) · [Wiki home](Home.md) +## Worktree and PR workflow + +Every task, including small fixes and documentation, uses this sequence: + +**Dedicated worktree + task branch -> local implementation and verification +-> atomic commit -> push and PR -> completed review and resolved findings +-> rebase merge into `main` -> verify and sync main -> remove merged task +branches and worktree.** + +Push, PR creation, merge, direct pushes to `main`, Wiki publication, and deployment +require authorization covering those actions. The sequence does not grant it; +existing authorization within the same scope does not need confirmation again. +SubMan retains its current CI and local checks. FlareMail's PRE acceptance gate +is not required here, and ordinary development does not publish or deploy. + +Before editing, inspect the original checkout, fetch and verify `origin/main`, +then create a new task branch and separate checkout. Replace the example topic +and path for each task: + +```bash +pwd +git status --short --branch +git rev-parse --abbrev-ref --symbolic-full-name '@{u}' +git worktree list +git fetch origin main +git rev-parse origin/main +git worktree add -b feat/topic ../SubMan-topic origin/main +cd ../SubMan-topic +``` + +Use `fix/`, `docs/`, or another Conventional Commit type as +appropriate. Record the absolute worktree path, branch, and base SHA. Resume an +existing task in its existing worktree; use another base only when requested. +Keep the original checkout intact and do not develop directly on `main`. +Preserve unrelated changes without reset, stash, or rewriting another task's history. + +Install locked dependencies in the task worktree. Keep `.svelte-kit`, `build`, +`.wrangler` (including local DO SQLite), browser state, and ports isolated. +Do not share writable generated directories or copy private configs/credentials +automatically. Implement, run applicable checks below, and create an atomic +Conventional Commit. With authorization, push the task branch and open a PR to +`main` using the repository PR template. Describe the problem, final behavior, +base and tested SHAs, validation evidence, and limitations. For multiline GitHub +CLI bodies, write a temporary file and pass `--body-file`. + +## Review before merge + +Every PR, including documentation/instruction changes, requires completed Codex +Code Review of the current head. After PR creation or any new commit, actively +check whether review has started. Verify actual repository review configuration; +FlareMail's enabled integrations do not establish SubMan's settings. Require +Security Review and any other configured required reviews when enabled. Missing +review activity does not prove an integration is disabled. + +Verify the actual author (`chatgpt-codex-connector[bot]`, sometimes shown without +`[bot]`), reviewed commit, completion time, and result links. Inspect each review +item's status and commit in `Codex Review Summary`, submitted reviews, and inline +findings. A single summary status/head SHA does not establish every review's +completion. `CLEAN`, empty Actions checks, `COMMENTED`, reactions, and old-head +reviews are insufficient. Required CI checks and bot review are separate gates. + +Fix valid blocking findings and rerun affected checks; document evidence for false +positives or inapplicable findings. Any new commit requires review of the new head. +Pending, failed, or unverifiable review means retaining the PR, branch, and worktree +and reporting the blocker. Elapsed time does not waive review. Do not enable +auto-merge before all gates have passed. + +## Rebase merge and cleanup + +For an authorized merge, verify the PR targets `main`, inspect its head SHA, +commits/files, mergeability, required CI checks, and current-head reviews. Default +to rebase unless another strategy was requested; lock the merge to the verified +head: + +```bash +gh pr merge --rebase --match-head-commit +``` + +Do not bypass checks with `--admin`. A merge queue or auto-merge request is not +completion; confirm PR state `MERGED` before cleanup. Record the PR URL, original +head SHA, and merge SHA. Fetch `origin/main` and verify it contains the merge SHA +and all task changes. Rebase changes SHA identities: compare original and rebased +commit ranges with patch/content checks such as `git range-diff`. Neither original +head ancestry nor a successful push proves integration. Do not compare the entire +task tree to a main branch that also contains unrelated changes. Content changes +from conflict resolution or integration require affected verification again. + +From the preserved original checkout, sync only when it is on `main`, clean, +and can fast-forward: + +```bash +git merge --ff-only origin/main +``` + +Keep dirty/diverged main checkouts intact and report the limitation; do not reset, +stash, or automatically rebase. Independently safe task cleanup may still proceed. +After a verified authorized merge, cleanup is part of completion unless the user +requests retention: + +1. Verify remaining local and remote task branches still point to the merged PR + head with no later commits. Inspect staged, unstaged, untracked, and valuable + ignored files. Preserve validation evidence and private configuration outside + the disposable worktree; stop its temporary services. Never remove another + task's worktree or the main checkout. +2. From a retained checkout, run `git worktree remove ` without `--force`, + then `git branch -d `. Do not combine cleanup with the merge command; + verify each result separately. +3. Delete a remaining remote branch only with a lease pinned to the verified + merged PR head: + `git push --force-with-lease=refs/heads/: origin :refs/heads/`. + This is conditional deletion, not permission to overwrite history. Do not use + unconditional `--delete` or `--force`. If already absent, record that result. + A rejected lease means preserving the branch and reporting it; do not retry + deletion using a newer unmerged head. +4. If `-d` refuses solely because rebase changed ancestry, `-D` is allowed only + after proving PR `MERGED`, merge SHA in main, unchanged task head, and equivalent + patches/content. A successful `-d` alone is not integration proof. Unmerged + commits, unsaved files, another worktree using the branch, or a retention + request stop the affected cleanup. +5. Verify PR state, local/remote main SHAs, working tree status, and removal of + task branches/worktree. Report PR URL, final SHA, validation, sync and cleanup + results, and blockers. Retain unmerged tasks. Merge and cleanup do not deploy + production. + ## Toolchain and local servers Use Bun **1.3.14**, matching `package.json` and CI: @@ -32,6 +156,13 @@ tests use synthetic data and mocks; do not add a real GitHub token for test writ ## Verification +For documentation/instruction-only changes, run `bun run docs:check` and review +the diff, commands, and links. Runtime tests and remote deployment are not needed. +Implementation, test, tooling, or CI changes require applicable checks below; +report missing prerequisites or failures rather than claiming a pass. Run checks +that share generated files (`check`, build, Worker tests, type generation, and +browser tests) sequentially in each worktree. + ```bash bun run docs:check bun test diff --git a/docs/wiki/Development.zh-CN.md b/docs/wiki/Development.zh-CN.md index 2601b5f..36df8a4 100644 --- a/docs/wiki/Development.zh-CN.md +++ b/docs/wiki/Development.zh-CN.md @@ -2,6 +2,101 @@ [English](Development.md) | 简体中文 · [Wiki 首页](Home.zh-CN.md) +## Worktree 与 PR 工作流 + +每项任务(包括小修复和文档更新)都使用以下顺序: + +**独立 worktree + 任务分支 → 本地实现与验证 → 原子提交 → 推送并提 PR +→ review 完成并处理反馈 → rebase 合并到 `main` → 核对并同步主分支 +→ 清理已合并任务的分支和 worktree。** + +推送、创建 PR、合并、直接推送 `main`、Wiki 发布和部署需要覆盖对应动作的授权。 +流程本身不额外授予权限;同一范围内已有明确授权的动作无需重复确认。 +SubMan 保留现有 CI 和本地验证,不引入 FlareMail 的 PRE 验收门禁;普通开发不自动发布或部署。 + +修改前检查原工作树,fetch 并核对 `origin/main`,再创建新任务分支和独立 checkout。 +每项任务替换以下示例中的主题与路径: + +```bash +pwd +git status --short --branch +git rev-parse --abbrev-ref --symbolic-full-name '@{u}' +git worktree list +git fetch origin main +git rev-parse origin/main +git worktree add -b feat/topic ../SubMan-topic origin/main +cd ../SubMan-topic +``` + +修复和文档分别使用 `fix/`、`docs/`,其他任务使用相应 Conventional Commit 类型。 +记录 worktree 绝对路径、分支和基线 SHA。继续已有任务时复用对应 worktree; +只有用户要求时才换用其他基线。保留原 checkout,不直接在 `main` 开发。 +保留无关改动,不 reset、stash 或改写其他任务的历史。 + +在任务 worktree 内安装锁定依赖。分别隔离 `.svelte-kit`、`build`、`.wrangler` +(包括本地 DO SQLite)、浏览器状态和端口,不共用可写生成目录,不自动复制私有配置或凭据。 +实现后完成下文适用的检查,再创建原子 Conventional Commit。获得授权后推送任务分支, +使用仓库 PR 模板向 `main` 提 PR,写明问题、最终行为、基线及验证 SHA、验证证据与限制。 +GitHub CLI 多行正文先写入临时文件,再通过 `--body-file` 传入。 + +## 合并前 Review + +所有 PR(包括文档和开发约束更新)都必须完成针对当前 head 的 Codex Code Review。 +创建 PR 或追加提交后主动检查审查是否触发。核对仓库实际的 review 配置,不能因为 +FlareMail 启用了集成就假定 SubMan 也已启用。Security Review 及其他必需审查启用时, +也必须逐项完成。尚未出现审查记录不能视为集成已关闭。 + +核对真实作者(`chatgpt-codex-connector[bot]`,部分输出省略 `[bot]`)、审查提交、 +完成时间和结果链接。检查 `Codex Review Summary` 中每项审查的状态与提交,结合 +已提交 review 和行内反馈判断。单个汇总 status/head SHA 不代表所有审查都已完成。 +`CLEAN`、空 Actions checks、`COMMENTED`、表情或旧 head 的 review 均不能作为完成证据。 +必需 CI 检查与机器人审查分别验收。 + +修复有效阻断问题并补做受影响检查;误报或不适用项记录依据。追加任何提交后, +都要等待新 head 的审查。审查待完成、失败或缺少可核实凭据时,保留 PR、分支和 worktree, +报告阻塞原因。等待超时不豁免审查,不提前开启可能绕过门禁的 auto-merge。 + +## Rebase 合并与清理 + +获得合并授权后,核对 PR 目标为 `main`、head SHA、提交/文件范围、可合并状态、 +必需 CI 检查与当前 head 的审查。用户未指定其他策略时默认 rebase 合并,锁定已验证 head: + +```bash +gh pr merge --rebase --match-head-commit +``` + +不通过 `--admin` 绕过检查。加入合并队列或开启 auto-merge 不代表已合并,清理前必须确认 +PR 为 `MERGED`。记录 PR URL、原 head SHA 和合并 SHA。fetch `origin/main`, +确认它包含合并 SHA 及任务全部改动。Rebase 会改写 SHA,使用补丁/内容对比核对原始与 +rebase 后的提交范围,例如 `git range-diff`。不能只凭原 head 的祖先关系或推送成功判断整合结果, +也不要求整个任务树与含其他改动的最新 main 完全相等。冲突解决或整合导致内容变化时补做受影响验证。 + +从保留的原 checkout 同步主分支,仅在当前为 `main`、工作树干净且能快进时执行: + +```bash +git merge --ff-only origin/main +``` + +主工作树有改动或分叉时保留现场并报告,不 reset、stash 或自动 rebase。 +这不妨碍已独立核实可安全执行的任务清理。核实已授权的合并完成后,默认完成收尾,用户要求保留时除外: + +1. 确认尚存的本地和远端任务分支仍指向已合并 PR head,没有新增提交。 + 检查暂存、未提交、未跟踪文件及需保留的忽略文件,把验收证据和私有配置保存到任务工作树之外, + 停止临时服务。不删除其他任务 worktree 或主 checkout。 +2. 从保留的 checkout 运行 `git worktree remove `,不加 `--force`, + 再运行 `git branch -d `。清理与合并分步执行,逐项核对结果。 +3. 尚存远端分支只能使用锁定已核实合并 head 的 lease 删除: + `git push --force-with-lease=refs/heads/: origin :refs/heads/`。 + 这是条件删除,不授权覆盖历史;不使用无条件 `--delete` 或 `--force`。 + 分支已不存在时记录即可。Lease 被拒绝时保留分支并报告,不换成较新的未合并 head 重试删除。 +4. `-d` 仅因 rebase 改写祖先关系而失败时,先证明 PR `MERGED`、合并 SHA 在 main、 + 任务 head 未变、补丁/内容等价,才能对本任务分支使用 `-D`。 + 单独的 `-d` 成功不证明改动进入 main。未合并提交、未保存文件、其他 worktree 占用, + 或用户要求保留时,停止对应清理。 +5. 核对 PR 状态、本地/远端 main SHA、工作树状态、任务分支和 worktree 移除结果。 + 交付 PR URL、最终 SHA、验证、同步与清理结果及阻塞项。未合并任务继续保留。 + 合并和清理不代表生产部署。 + ## 工具链与本地服务 使用与 `package.json`、CI 一致的 Bun **1.3.14**: @@ -30,6 +125,10 @@ bun run preview -- --host :: --port 4173 ## 验证 +纯文档/开发约束改动运行 `bun run docs:check`,审阅差异、命令和链接,无需运行时测试或远程部署。 +实现、测试、工具或 CI 改动执行下方适用检查;前置条件缺失或检查失败时如实报告。 +共享生成文件的检查(`check`、构建、Worker 测试、类型生成、浏览器测试)在同一 worktree 内串行运行。 + ```bash bun run docs:check bun test