From 707e00d85a6dcffa54e554ffb1a8f2f9337ab883 Mon Sep 17 00:00:00 2001 From: lorne <1991wangliang@gmail.com> Date: Sat, 7 Nov 2026 14:49:33 +0800 Subject: [PATCH 1/5] Update flow-frontend to latest main --- flow-frontend | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/flow-frontend b/flow-frontend index 337b0f78..c56efd40 160000 --- a/flow-frontend +++ b/flow-frontend @@ -1 +1 @@ -Subproject commit 337b0f78fcedb2bc58d5f19bdccca6a63d595540 +Subproject commit c56efd40402d088a435b6dbb7ff4367e9681616f From 5b835b628667762298afb3839c9968471d506b8a Mon Sep 17 00:00:00 2001 From: lorne <1991wangliang@gmail.com> Date: Sat, 7 Nov 2026 16:08:46 +0800 Subject: [PATCH 2/5] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20GitHub=20Issue?= =?UTF-8?q?=20=E6=A0=87=E5=87=86=E5=A4=84=E7=90=86=E6=B5=81=E7=A8=8B?= =?UTF-8?q?=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 统一 issue 定位分析、回复、worktree 修复、合并 dev、提交关联与完成后回复的流程,避免每次重复强调。 Refs #246 --- AGENTS.md | 12 ++ docs/conventions/index.md | 9 +- docs/conventions/workflow/github-issue.md | 140 ++++++++++++++++++++++ 3 files changed, 160 insertions(+), 1 deletion(-) create mode 100644 docs/conventions/workflow/github-issue.md diff --git a/AGENTS.md b/AGENTS.md index 132c8f2d..2da572e8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,6 +100,18 @@ cd flow-engine-example && mvn spring-boot:run - **未经用户明确要求,任何情况下不得执行 `git commit` / `git push` / `git merge` 操作** - 所有代码变更需经用户审核后再提交 +### GitHub Issue 标准处理流程 + +处理任何来自 GitHub 的 issue 时,必须遵循 [docs/conventions/workflow/github-issue.md](./docs/conventions/workflow/github-issue.md): + +1. **定位阶段**可只读代码分析,不必创建 worktree; +2. **定位完成后先回复 issue**,说明根因与处理方案; +3. **实际改代码必须使用 git worktree + 特性分支**(基于 `dev`),不得在主工作区直接修改; +4. 修复需测试先行并完成本地编译/测试验证; +5. 完成后**只合并到 `dev` 分支,不执行 `git push`**,是否推送到 GitHub 由用户决定; +6. 提交信息使用 `Closes #` 关联 issue;进入默认分支后自动关闭,未自动关闭时需用户确认后手动关闭; +7. **代码合入后再次回复 issue**,说明修复内容、验证结果与合入分支。 + ### 基本规范 - **与用户沟通及编写文档时,所有内容必须使用中文表述** diff --git a/docs/conventions/index.md b/docs/conventions/index.md index 04276e5b..2136ca17 100644 --- a/docs/conventions/index.md +++ b/docs/conventions/index.md @@ -2,5 +2,12 @@ > 🔄 此文件由 `rebuild_pkr_index.py` 自动生成,请勿手动编辑。 -_暂无已注册的规范文档。_ +## ✅ 已实现 +| 名称 | 模块 | 描述 | 范围 | 来源 | +|------|------|------|------|------| +| [workflow/github-issue](./workflow/github-issue.md) | workflow | GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 合并 dev → 提交关闭 → 完成后回复 | 通用 | 项目自有 | + +--- + +**统计**: 共 1 篇 — 已实现 1 / 计划中 0 / 已废弃 0 diff --git a/docs/conventions/workflow/github-issue.md b/docs/conventions/workflow/github-issue.md new file mode 100644 index 00000000..2d39b027 --- /dev/null +++ b/docs/conventions/workflow/github-issue.md @@ -0,0 +1,140 @@ +--- +name: workflow/github-issue +module: workflow +description: GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 合并 dev → 提交关闭 → 完成后回复 +status: 已实现 +scope: 通用 +source: 项目自有 +--- + +## 解决什么问题 + +不遵守此流程会导致: + +- 问题分析结论只留在本地,issue 参与者无法同步进展 +- 直接在主干工作区改代码,污染工作区、难以回滚和并行处理多个 issue +- 修复完成后 issue 长期悬空,无法追溯「哪个提交解决了哪个 issue」 +- 分支、worktree、合并目标不统一,发布时遗漏改动 + +## 适用范围 + +`codingapi/flow-engine` 及其关联仓库(如 `codingapi/flow-frontend`)的**所有 GitHub issue**。 + +## 核心原则 + +1. **分析可以不开 worktree,改代码必须开**:定位阶段只读代码即可;一旦确定要修改,必须新建 git worktree + 特性分支。 +2. **先回复,再动手**:定位到问题后,先在对应 issue 回复根因与处理方案。 +3. **只合并到 dev**:特性分支完成后合并至 `dev`;是否推送 `dev` 到 GitHub 由维护者决定,助手不得擅自 `git push`。 +4. **提交即关联 issue**:提交信息使用 `Closes #` 关联;是否已真正关闭取决于是否进入默认分支,未自动关闭时由维护者确认后手动关闭。 +5. **完成后回复**:代码合入 `dev` 后,在 issue 回复修复内容、分支/提交与验证结果。 + +## 标准步骤 + +### 1. 读取 issue + +```bash +gh issue view --repo codingapi/flow-engine \ + --json number,title,state,labels,body,comments,author,createdAt +``` + +### 2. 定位问题(可不建 worktree) + +- 使用代码搜索、LSP、文档(`docs/conventions`、`docs/capabilities`)定位根因; +- 明确影响范围(后端 / PC 端 / 移动端)、是否涉及前端子模块 `flow-frontend`; +- 判断是否属于已有能力缺陷,优先复用既有机制而非新增。 + +### 3. 回复 issue(定位结论) + +将以下内容整理为中文评论: + +- 问题原因(引用具体类/文件/方法); +- 影响范围(哪些动作、端、版本); +- 处理方案(改动点、交互变化、兼容性); +- 交付方式(分支名、合并目标 `dev`)。 + +```bash +gh issue comment --repo codingapi/flow-engine --body-file /tmp/issue--analysis.md +``` + +### 4. 创建 worktree 与特性分支 + +**后端主仓库**(`.worktrees/` 已被 `.gitignore` 忽略): + +```bash +git worktree add .worktrees/issue- -b feature/issue-- dev +cd .worktrees/issue- +``` + +**前端子模块**(`flow-frontend/.claude/worktrees/` 已被忽略): + +```bash +cd flow-frontend +git worktree add .claude/worktrees/issue- -b feature/issue-- dev +cd .claude/worktrees/issue- +pnpm install --frozen-lockfile --prefer-offline # worktree 无 node_modules +``` + +命名约定:`feature/issue--<简短英文描述>`。 + +### 5. 修复与验证(TDD) + +- 先补测试(红灯),再实现(绿灯),最后重构; +- 前端:`npx rstest run`(单包)、`pnpm run test:`、`pnpm run build:`; +- 后端:`./mvnw -pl test`,必要时 `./mvnw clean install`; +- **修改代码后必须本地编译/测试通过**,失败项如实报告,不得声称已验证。 + +### 6. 合并到 dev(不推送) + +```bash +git checkout dev +git merge --no-ff feature/issue-- +# 不执行 git push,由维护者决定 +``` + +- 合并后保留或清理 worktree(`git worktree remove `); +- 若前后端均有改动,两个仓库分别合并到各自 `dev`; +- 不更新主仓库记录的 `flow-frontend` 子模块指针,除非维护者明确要求。 + +### 7. 提交信息与 issue 关闭 + +提交信息格式: + +``` +fix: <一句话描述> (<关联范围>) + +<可选的改动说明> + +Closes # +``` + +- `Closes #` 只在提交进入**默认分支**(`main`)时由 GitHub 自动关闭; +- 若先合入 `dev` 且尚未发布到 `main`,issue 保持打开,待 `dev → main` 合并时自动关闭; +- 如需提前关闭,必须由维护者确认后执行 `gh issue close `,不得擅自关闭。 + +### 8. 完成后回复 issue + +回复内容包含: + +- 根因与最终方案(与步骤 3 的差异); +- 变更文件/能力(新增公共 API、交互变化); +- 验证结果(测试用例数、构建结果); +- 合入分支与提交号; +- 升级/兼容提示(如有行为变更)。 + +## 禁止事项 + +- 未经用户明确要求,不得执行 `git push` / 直接向 `main` 提交; +- 不得在主工作区(非 worktree)直接修改业务代码; +- 不得跳过测试与编译验证; +- 不得在代码未合入前擅自关闭 issue; +- 不得用相对路径跨 package 引用(前端规范)。 + +## 检查清单 + +- [ ] issue 已读取并确认现状 +- [ ] 定位结论已在 issue 回复 +- [ ] worktree + 特性分支已创建(基于 `dev`) +- [ ] 测试先行且全量通过,构建通过 +- [ ] 已合并到 `dev`(未推送) +- [ ] 提交信息包含 `Closes #` +- [ ] 完成后已在 issue 回复修复与验证结果 From 33b4e7f04deb4ea534e60b435fb7c50682202351 Mon Sep 17 00:00:00 2001 From: lorne <1991wangliang@gmail.com> Date: Sat, 7 Nov 2026 16:24:31 +0800 Subject: [PATCH 3/5] =?UTF-8?q?docs:=20issue=20=E5=AE=8C=E6=88=90=E5=9B=9E?= =?UTF-8?q?=E5=A4=8D=E8=B0=83=E6=95=B4=E5=88=B0=E6=8E=A8=E9=80=81=20GitHub?= =?UTF-8?q?=20=E4=B9=8B=E5=90=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 明确完成回复的前置条件:代码已推送到 GitHub;未推送前只说明本地进度,不发布完成结论。 --- AGENTS.md | 2 +- docs/conventions/index.md | 2 +- docs/conventions/workflow/github-issue.md | 12 ++++++++---- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2da572e8..ce806759 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -110,7 +110,7 @@ cd flow-engine-example && mvn spring-boot:run 4. 修复需测试先行并完成本地编译/测试验证; 5. 完成后**只合并到 `dev` 分支,不执行 `git push`**,是否推送到 GitHub 由用户决定; 6. 提交信息使用 `Closes #` 关联 issue;进入默认分支后自动关闭,未自动关闭时需用户确认后手动关闭; -7. **代码合入后再次回复 issue**,说明修复内容、验证结果与合入分支。 +7. **代码推送到 GitHub 后再回复 issue**,说明修复内容、验证结果与合入分支;未推送前不得发布完成回复(定位回复不受此限)。 ### 基本规范 diff --git a/docs/conventions/index.md b/docs/conventions/index.md index 2136ca17..767f45bd 100644 --- a/docs/conventions/index.md +++ b/docs/conventions/index.md @@ -6,7 +6,7 @@ | 名称 | 模块 | 描述 | 范围 | 来源 | |------|------|------|------|------| -| [workflow/github-issue](./workflow/github-issue.md) | workflow | GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 合并 dev → 提交关闭 → 完成后回复 | 通用 | 项目自有 | +| [workflow/github-issue](./workflow/github-issue.md) | workflow | GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 合并 dev → 提交关闭 → 推送 GitHub → 推送后回复 | 通用 | 项目自有 | --- diff --git a/docs/conventions/workflow/github-issue.md b/docs/conventions/workflow/github-issue.md index 2d39b027..a84c32c3 100644 --- a/docs/conventions/workflow/github-issue.md +++ b/docs/conventions/workflow/github-issue.md @@ -1,7 +1,7 @@ --- name: workflow/github-issue module: workflow -description: GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 合并 dev → 提交关闭 → 完成后回复 +description: GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 合并 dev → 提交关闭 → 推送 GitHub → 推送后回复 status: 已实现 scope: 通用 source: 项目自有 @@ -26,7 +26,7 @@ source: 项目自有 2. **先回复,再动手**:定位到问题后,先在对应 issue 回复根因与处理方案。 3. **只合并到 dev**:特性分支完成后合并至 `dev`;是否推送 `dev` 到 GitHub 由维护者决定,助手不得擅自 `git push`。 4. **提交即关联 issue**:提交信息使用 `Closes #` 关联;是否已真正关闭取决于是否进入默认分支,未自动关闭时由维护者确认后手动关闭。 -5. **完成后回复**:代码合入 `dev` 后,在 issue 回复修复内容、分支/提交与验证结果。 +5. **推送后再回复**:代码推送到 GitHub(由维护者执行或授权)之后,才在 issue 回复修复内容、提交与验证结果;**未推送前不得发布完成回复**。 ## 标准步骤 @@ -111,7 +111,9 @@ Closes # - 若先合入 `dev` 且尚未发布到 `main`,issue 保持打开,待 `dev → main` 合并时自动关闭; - 如需提前关闭,必须由维护者确认后执行 `gh issue close `,不得擅自关闭。 -### 8. 完成后回复 issue +### 8. 推送 GitHub 后回复 issue + +**前置条件:代码已推送到 GitHub**(`dev` 或其他目标分支)。推送由维护者执行或明确授权,助手不得自行推送;未推送前只可说明「修复已在本地 `dev` 完成,待推送」,不得发布完成结论。 回复内容包含: @@ -126,6 +128,7 @@ Closes # - 未经用户明确要求,不得执行 `git push` / 直接向 `main` 提交; - 不得在主工作区(非 worktree)直接修改业务代码; - 不得跳过测试与编译验证; +- 不得在代码推送到 GitHub 前发布完成回复(定位回复不受此限); - 不得在代码未合入前擅自关闭 issue; - 不得用相对路径跨 package 引用(前端规范)。 @@ -137,4 +140,5 @@ Closes # - [ ] 测试先行且全量通过,构建通过 - [ ] 已合并到 `dev`(未推送) - [ ] 提交信息包含 `Closes #` -- [ ] 完成后已在 issue 回复修复与验证结果 +- [ ] 代码已推送到 GitHub(维护者执行或确认授权) +- [ ] 推送后已在 issue 回复修复与验证结果 From 29718f692e69079794d851958506fa769dc0db2e Mon Sep 17 00:00:00 2001 From: lorne <1991wangliang@gmail.com> Date: Sat, 7 Nov 2026 16:28:24 +0800 Subject: [PATCH 4/5] =?UTF-8?q?docs:=20issue=20=E6=B5=81=E7=A8=8B=E6=94=B9?= =?UTF-8?q?=E4=B8=BA=E6=8E=A8=E9=80=81=E7=89=B9=E6=80=A7=E5=88=86=E6=94=AF?= =?UTF-8?q?=EF=BC=8C=E4=B8=8D=E5=90=88=E5=B9=B6=20dev?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 每个 issue 从 dev 新建特性分支,完成后仅推送特性分支到 GitHub,由维护者评审合并 dev;完成回复仍以推送为前提。 --- AGENTS.md | 4 +-- docs/conventions/index.md | 2 +- docs/conventions/workflow/github-issue.md | 40 +++++++++++------------ 3 files changed, 23 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ce806759..5638955f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,9 +108,9 @@ cd flow-engine-example && mvn spring-boot:run 2. **定位完成后先回复 issue**,说明根因与处理方案; 3. **实际改代码必须使用 git worktree + 特性分支**(基于 `dev`),不得在主工作区直接修改; 4. 修复需测试先行并完成本地编译/测试验证; -5. 完成后**只合并到 `dev` 分支,不执行 `git push`**,是否推送到 GitHub 由用户决定; +5. 完成后**只推送该 issue 的特性分支到 GitHub**,不合并 `dev`、不推送 `dev` / `main`,`dev` 由维护者评审后合并; 6. 提交信息使用 `Closes #` 关联 issue;进入默认分支后自动关闭,未自动关闭时需用户确认后手动关闭; -7. **代码推送到 GitHub 后再回复 issue**,说明修复内容、验证结果与合入分支;未推送前不得发布完成回复(定位回复不受此限)。 +7. **特性分支推送到 GitHub 后再回复 issue**,说明修复内容、验证结果与推送分支/提交;未推送前不得发布完成回复(定位回复不受此限)。 ### 基本规范 diff --git a/docs/conventions/index.md b/docs/conventions/index.md index 767f45bd..e3e83e9e 100644 --- a/docs/conventions/index.md +++ b/docs/conventions/index.md @@ -6,7 +6,7 @@ | 名称 | 模块 | 描述 | 范围 | 来源 | |------|------|------|------|------| -| [workflow/github-issue](./workflow/github-issue.md) | workflow | GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 合并 dev → 提交关闭 → 推送 GitHub → 推送后回复 | 通用 | 项目自有 | +| [workflow/github-issue](./workflow/github-issue.md) | workflow | GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 推送特性分支 → 推送后回复 | 通用 | 项目自有 | --- diff --git a/docs/conventions/workflow/github-issue.md b/docs/conventions/workflow/github-issue.md index a84c32c3..b4ccc0fd 100644 --- a/docs/conventions/workflow/github-issue.md +++ b/docs/conventions/workflow/github-issue.md @@ -1,7 +1,7 @@ --- name: workflow/github-issue module: workflow -description: GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 合并 dev → 提交关闭 → 推送 GitHub → 推送后回复 +description: GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 推送特性分支 → 推送后回复 status: 已实现 scope: 通用 source: 项目自有 @@ -24,9 +24,9 @@ source: 项目自有 1. **分析可以不开 worktree,改代码必须开**:定位阶段只读代码即可;一旦确定要修改,必须新建 git worktree + 特性分支。 2. **先回复,再动手**:定位到问题后,先在对应 issue 回复根因与处理方案。 -3. **只合并到 dev**:特性分支完成后合并至 `dev`;是否推送 `dev` 到 GitHub 由维护者决定,助手不得擅自 `git push`。 +3. **基于 dev 开分支,不直接合并 dev**:每个 issue 都从 `dev` 新建独立特性分支;完成后只把特性分支推送到 GitHub,由维护者评审后合并到 `dev`。助手不得自行合并 `dev`,也不得向 `dev` / `main` 推送。 4. **提交即关联 issue**:提交信息使用 `Closes #` 关联;是否已真正关闭取决于是否进入默认分支,未自动关闭时由维护者确认后手动关闭。 -5. **推送后再回复**:代码推送到 GitHub(由维护者执行或授权)之后,才在 issue 回复修复内容、提交与验证结果;**未推送前不得发布完成回复**。 +5. **推送后再回复**:特性分支推送到 GitHub 之后,才在 issue 回复修复内容、提交与验证结果;**未推送前不得发布完成回复**。 ## 标准步骤 @@ -50,7 +50,7 @@ gh issue view --repo codingapi/flow-engine \ - 问题原因(引用具体类/文件/方法); - 影响范围(哪些动作、端、版本); - 处理方案(改动点、交互变化、兼容性); -- 交付方式(分支名、合并目标 `dev`)。 +- 交付方式(基于 `dev` 的特性分支名,完成后由维护者合并)。 ```bash gh issue comment --repo codingapi/flow-engine --body-file /tmp/issue--analysis.md @@ -83,17 +83,17 @@ pnpm install --frozen-lockfile --prefer-offline # worktree 无 node_modules - 后端:`./mvnw -pl test`,必要时 `./mvnw clean install`; - **修改代码后必须本地编译/测试通过**,失败项如实报告,不得声称已验证。 -### 6. 合并到 dev(不推送) +### 6. 推送特性分支到 GitHub(不合并 dev) ```bash -git checkout dev -git merge --no-ff feature/issue-- -# 不执行 git push,由维护者决定 +git push -u origin feature/issue-- ``` -- 合并后保留或清理 worktree(`git worktree remove `); -- 若前后端均有改动,两个仓库分别合并到各自 `dev`; -- 不更新主仓库记录的 `flow-frontend` 子模块指针,除非维护者明确要求。 +- 只推送该 issue 的特性分支,`dev` 保持不动,由维护者评审后合并; +- 禁止推送到 `dev` / `main`,禁止在本地合并 `dev`; +- 前后端均有改动时,两个仓库各自推送自己的特性分支; +- 不更新主仓库记录的 `flow-frontend` 子模块指针,除非维护者明确要求; +- 推送后可清理本地 worktree(`git worktree remove `),分支保留。 ### 7. 提交信息与 issue 关闭 @@ -108,28 +108,29 @@ Closes # ``` - `Closes #` 只在提交进入**默认分支**(`main`)时由 GitHub 自动关闭; -- 若先合入 `dev` 且尚未发布到 `main`,issue 保持打开,待 `dev → main` 合并时自动关闭; +- 推送到特性分支不会关闭 issue;特性分支合并到 `dev` 后仍保持打开,待 `dev → main` 合并时自动关闭; - 如需提前关闭,必须由维护者确认后执行 `gh issue close `,不得擅自关闭。 -### 8. 推送 GitHub 后回复 issue +### 8. 推送后回复 issue -**前置条件:代码已推送到 GitHub**(`dev` 或其他目标分支)。推送由维护者执行或明确授权,助手不得自行推送;未推送前只可说明「修复已在本地 `dev` 完成,待推送」,不得发布完成结论。 +**前置条件:特性分支已推送到 GitHub**。未推送前只可说明「修复已提交到本地特性分支,待推送」,不得发布完成结论。 回复内容包含: - 根因与最终方案(与步骤 3 的差异); - 变更文件/能力(新增公共 API、交互变化); - 验证结果(测试用例数、构建结果); -- 合入分支与提交号; +- 推送分支与提交号、对应 PR/评审状态; - 升级/兼容提示(如有行为变更)。 ## 禁止事项 -- 未经用户明确要求,不得执行 `git push` / 直接向 `main` 提交; +- 不得向 `dev` / `main` 推送,不得在本地合并 `dev`(合并由维护者评审完成); +- 特性分支推送是标准步骤,但推送前必须确认远程分支名,避免误推; - 不得在主工作区(非 worktree)直接修改业务代码; - 不得跳过测试与编译验证; -- 不得在代码推送到 GitHub 前发布完成回复(定位回复不受此限); -- 不得在代码未合入前擅自关闭 issue; +- 不得在特性分支推送前发布完成回复(定位回复不受此限); +- 不得在代码未进入默认分支前擅自关闭 issue; - 不得用相对路径跨 package 引用(前端规范)。 ## 检查清单 @@ -138,7 +139,6 @@ Closes # - [ ] 定位结论已在 issue 回复 - [ ] worktree + 特性分支已创建(基于 `dev`) - [ ] 测试先行且全量通过,构建通过 -- [ ] 已合并到 `dev`(未推送) +- [ ] 特性分支已推送到 GitHub(`dev` 未改动) - [ ] 提交信息包含 `Closes #` -- [ ] 代码已推送到 GitHub(维护者执行或确认授权) - [ ] 推送后已在 issue 回复修复与验证结果 From 4e05b76b070358e06d80b3f806476e4ac8ed7ae2 Mon Sep 17 00:00:00 2001 From: lorne <1991wangliang@gmail.com> Date: Sat, 7 Nov 2026 16:37:06 +0800 Subject: [PATCH 5/5] =?UTF-8?q?docs:=20=E6=98=8E=E7=A1=AE=20dev=20?= =?UTF-8?q?=E4=BB=85=E4=BD=9C=E4=B8=BA=20issue=20=E5=88=86=E6=94=AF?= =?UTF-8?q?=E5=9F=BA=E7=BA=BF=EF=BC=8C=E4=B8=8D=E5=8F=82=E4=B8=8E=E4=BA=A4?= =?UTF-8?q?=E4=BB=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit issue 完成后只推送特性分支,提交、推送与 issue 关联均基于该分支;是否合并 dev 由人工决定,任务完成仅提示分支与 PR 链接。 --- AGENTS.md | 4 ++-- docs/conventions/workflow/github-issue.md | 11 +++++++---- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5638955f..ef0a810f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -106,9 +106,9 @@ cd flow-engine-example && mvn spring-boot:run 1. **定位阶段**可只读代码分析,不必创建 worktree; 2. **定位完成后先回复 issue**,说明根因与处理方案; -3. **实际改代码必须使用 git worktree + 特性分支**(基于 `dev`),不得在主工作区直接修改; +3. **实际改代码必须使用 git worktree + 特性分支**(worktree 仅以 `dev` 代码为基线),不得在主工作区直接修改; 4. 修复需测试先行并完成本地编译/测试验证; -5. 完成后**只推送该 issue 的特性分支到 GitHub**,不合并 `dev`、不推送 `dev` / `main`,`dev` 由维护者评审后合并; +5. 完成后**只推送该 issue 的特性分支到 GitHub**:提交内容、推送与 issue 关联均以该特性分支为准,**不合并 `dev`**;是否合并 `dev` 由人工决定,任务完成时仅提示分支与 PR 链接; 6. 提交信息使用 `Closes #` 关联 issue;进入默认分支后自动关闭,未自动关闭时需用户确认后手动关闭; 7. **特性分支推送到 GitHub 后再回复 issue**,说明修复内容、验证结果与推送分支/提交;未推送前不得发布完成回复(定位回复不受此限)。 diff --git a/docs/conventions/workflow/github-issue.md b/docs/conventions/workflow/github-issue.md index b4ccc0fd..4d1e15b8 100644 --- a/docs/conventions/workflow/github-issue.md +++ b/docs/conventions/workflow/github-issue.md @@ -24,7 +24,7 @@ source: 项目自有 1. **分析可以不开 worktree,改代码必须开**:定位阶段只读代码即可;一旦确定要修改,必须新建 git worktree + 特性分支。 2. **先回复,再动手**:定位到问题后,先在对应 issue 回复根因与处理方案。 -3. **基于 dev 开分支,不直接合并 dev**:每个 issue 都从 `dev` 新建独立特性分支;完成后只把特性分支推送到 GitHub,由维护者评审后合并到 `dev`。助手不得自行合并 `dev`,也不得向 `dev` / `main` 推送。 +3. **dev 只作为基线,不参与交付**:worktree 基于 `dev` 代码创建;修复提交、推送与 issue 关联全部发生在该 issue 的特性分支上。完成后**不合并 `dev`**,是否合并由人工决定,助手只在任务完成时提示分支与 PR 链接。 4. **提交即关联 issue**:提交信息使用 `Closes #` 关联;是否已真正关闭取决于是否进入默认分支,未自动关闭时由维护者确认后手动关闭。 5. **推送后再回复**:特性分支推送到 GitHub 之后,才在 issue 回复修复内容、提交与验证结果;**未推送前不得发布完成回复**。 @@ -76,6 +76,8 @@ pnpm install --frozen-lockfile --prefer-offline # worktree 无 node_modules 命名约定:`feature/issue--<简短英文描述>`。 +> worktree 仅以 `dev` 代码为**基线**;创建之后的所有提交、推送与 issue 关联都只发生在该特性分支上,`dev` 不参与交付。 + ### 5. 修复与验证(TDD) - 先补测试(红灯),再实现(绿灯),最后重构; @@ -83,14 +85,15 @@ pnpm install --frozen-lockfile --prefer-offline # worktree 无 node_modules - 后端:`./mvnw -pl test`,必要时 `./mvnw clean install`; - **修改代码后必须本地编译/测试通过**,失败项如实报告,不得声称已验证。 -### 6. 推送特性分支到 GitHub(不合并 dev) +### 6. 推送特性分支到 GitHub(任务到此结束) ```bash git push -u origin feature/issue-- ``` -- 只推送该 issue 的特性分支,`dev` 保持不动,由维护者评审后合并; +- 只推送该 issue 的特性分支,`dev` 保持不动,是否合并由人工决定; - 禁止推送到 `dev` / `main`,禁止在本地合并 `dev`; +- 任务完成提示中给出分支地址与 PR 链接即可,不代为合并; - 前后端均有改动时,两个仓库各自推送自己的特性分支; - 不更新主仓库记录的 `flow-frontend` 子模块指针,除非维护者明确要求; - 推送后可清理本地 worktree(`git worktree remove `),分支保留。 @@ -125,7 +128,7 @@ Closes # ## 禁止事项 -- 不得向 `dev` / `main` 推送,不得在本地合并 `dev`(合并由维护者评审完成); +- 不得向 `dev` / `main` 推送,不得在本地合并 `dev`(是否合并由人工决定); - 特性分支推送是标准步骤,但推送前必须确认远程分支名,避免误推; - 不得在主工作区(非 worktree)直接修改业务代码; - 不得跳过测试与编译验证;