Skip to content

Commit 7c4c3bc

Browse files
authored
Merge pull request #248 from codingapi/docs/issue-workflow
Docs/issue workflow
2 parents 46564e6 + 4e05b76 commit 7c4c3bc

4 files changed

Lines changed: 168 additions & 2 deletions

File tree

‎AGENTS.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,18 @@ cd flow-engine-example && mvn spring-boot:run
100100
- **未经用户明确要求,任何情况下不得执行 `git commit` / `git push` / `git merge` 操作**
101101
- 所有代码变更需经用户审核后再提交
102102

103+
### GitHub Issue 标准处理流程
104+
105+
处理任何来自 GitHub 的 issue 时,必须遵循 [docs/conventions/workflow/github-issue.md](./docs/conventions/workflow/github-issue.md):
106+
107+
1. **定位阶段**可只读代码分析,不必创建 worktree;
108+
2. **定位完成后先回复 issue**,说明根因与处理方案;
109+
3. **实际改代码必须使用 git worktree + 特性分支**(worktree 仅以 `dev` 代码为基线),不得在主工作区直接修改;
110+
4. 修复需测试先行并完成本地编译/测试验证;
111+
5. 完成后**只推送该 issue 的特性分支到 GitHub**:提交内容、推送与 issue 关联均以该特性分支为准,**不合并 `dev`**;是否合并 `dev` 由人工决定,任务完成时仅提示分支与 PR 链接;
112+
6. 提交信息使用 `Closes #<issue编号>` 关联 issue;进入默认分支后自动关闭,未自动关闭时需用户确认后手动关闭;
113+
7. **特性分支推送到 GitHub 后再回复 issue**,说明修复内容、验证结果与推送分支/提交;未推送前不得发布完成回复(定位回复不受此限)。
114+
103115
### 基本规范
104116

105117
- **与用户沟通及编写文档时,所有内容必须使用中文表述**

‎docs/conventions/index.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,12 @@
22

33
> 🔄 此文件由 `rebuild_pkr_index.py` 自动生成,请勿手动编辑。
44
5-
_暂无已注册的规范文档。_
5+
## ✅ 已实现
66

7+
| 名称 | 模块 | 描述 | 范围 | 来源 |
8+
|------|------|------|------|------|
9+
| [workflow/github-issue](./workflow/github-issue.md) | workflow | GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 推送特性分支 → 推送后回复 | 通用 | 项目自有 |
10+
11+
---
12+
13+
**统计**: 共 1 篇 — 已实现 1 / 计划中 0 / 已废弃 0
Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
name: workflow/github-issue
3+
module: workflow
4+
description: GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 推送特性分支 → 推送后回复
5+
status: 已实现
6+
scope: 通用
7+
source: 项目自有
8+
---
9+
10+
## 解决什么问题
11+
12+
不遵守此流程会导致:
13+
14+
- 问题分析结论只留在本地,issue 参与者无法同步进展
15+
- 直接在主干工作区改代码,污染工作区、难以回滚和并行处理多个 issue
16+
- 修复完成后 issue 长期悬空,无法追溯「哪个提交解决了哪个 issue」
17+
- 分支、worktree、合并目标不统一,发布时遗漏改动
18+
19+
## 适用范围
20+
21+
`codingapi/flow-engine` 及其关联仓库(如 `codingapi/flow-frontend`)的**所有 GitHub issue**。
22+
23+
## 核心原则
24+
25+
1. **分析可以不开 worktree,改代码必须开**:定位阶段只读代码即可;一旦确定要修改,必须新建 git worktree + 特性分支。
26+
2. **先回复,再动手**:定位到问题后,先在对应 issue 回复根因与处理方案。
27+
3. **dev 只作为基线,不参与交付**:worktree 基于 `dev` 代码创建;修复提交、推送与 issue 关联全部发生在该 issue 的特性分支上。完成后**不合并 `dev`**,是否合并由人工决定,助手只在任务完成时提示分支与 PR 链接。
28+
4. **提交即关联 issue**:提交信息使用 `Closes #<id>` 关联;是否已真正关闭取决于是否进入默认分支,未自动关闭时由维护者确认后手动关闭。
29+
5. **推送后再回复**:特性分支推送到 GitHub 之后,才在 issue 回复修复内容、提交与验证结果;**未推送前不得发布完成回复**。
30+
31+
## 标准步骤
32+
33+
### 1. 读取 issue
34+
35+
```bash
36+
gh issue view <id> --repo codingapi/flow-engine \
37+
--json number,title,state,labels,body,comments,author,createdAt
38+
```
39+
40+
### 2. 定位问题(可不建 worktree)
41+
42+
- 使用代码搜索、LSP、文档(`docs/conventions`、`docs/capabilities`)定位根因;
43+
- 明确影响范围(后端 / PC 端 / 移动端)、是否涉及前端子模块 `flow-frontend`;
44+
- 判断是否属于已有能力缺陷,优先复用既有机制而非新增。
45+
46+
### 3. 回复 issue(定位结论)
47+
48+
将以下内容整理为中文评论:
49+
50+
- 问题原因(引用具体类/文件/方法);
51+
- 影响范围(哪些动作、端、版本);
52+
- 处理方案(改动点、交互变化、兼容性);
53+
- 交付方式(基于 `dev` 的特性分支名,完成后由维护者合并)。
54+
55+
```bash
56+
gh issue comment <id> --repo codingapi/flow-engine --body-file /tmp/issue-<id>-analysis.md
57+
```
58+
59+
### 4. 创建 worktree 与特性分支
60+
61+
**后端主仓库**(`.worktrees/` 已被 `.gitignore` 忽略):
62+
63+
```bash
64+
git worktree add .worktrees/issue-<id> -b feature/issue-<id>-<slug> dev
65+
cd .worktrees/issue-<id>
66+
```
67+
68+
**前端子模块**(`flow-frontend/.claude/worktrees/` 已被忽略):
69+
70+
```bash
71+
cd flow-frontend
72+
git worktree add .claude/worktrees/issue-<id> -b feature/issue-<id>-<slug> dev
73+
cd .claude/worktrees/issue-<id>
74+
pnpm install --frozen-lockfile --prefer-offline # worktree 无 node_modules
75+
```
76+
77+
命名约定:`feature/issue-<issue编号>-<简短英文描述>`。
78+
79+
> worktree 仅以 `dev` 代码为**基线**;创建之后的所有提交、推送与 issue 关联都只发生在该特性分支上,`dev` 不参与交付。
80+
81+
### 5. 修复与验证(TDD)
82+
83+
- 先补测试(红灯),再实现(绿灯),最后重构;
84+
- 前端:`npx rstest run`(单包)、`pnpm run test:<package>`、`pnpm run build:<package>`;
85+
- 后端:`./mvnw -pl <module> test`,必要时 `./mvnw clean install`;
86+
- **修改代码后必须本地编译/测试通过**,失败项如实报告,不得声称已验证。
87+
88+
### 6. 推送特性分支到 GitHub(任务到此结束)
89+
90+
```bash
91+
git push -u origin feature/issue-<id>-<slug>
92+
```
93+
94+
- 只推送该 issue 的特性分支,`dev` 保持不动,是否合并由人工决定;
95+
- 禁止推送到 `dev` / `main`,禁止在本地合并 `dev`;
96+
- 任务完成提示中给出分支地址与 PR 链接即可,不代为合并;
97+
- 前后端均有改动时,两个仓库各自推送自己的特性分支;
98+
- 不更新主仓库记录的 `flow-frontend` 子模块指针,除非维护者明确要求;
99+
- 推送后可清理本地 worktree(`git worktree remove <path>`),分支保留。
100+
101+
### 7. 提交信息与 issue 关闭
102+
103+
提交信息格式:
104+
105+
```
106+
fix: <一句话描述> (<关联范围>)
107+
108+
<可选的改动说明>
109+
110+
Closes #<id>
111+
```
112+
113+
- `Closes #<id>` 只在提交进入**默认分支**(`main`)时由 GitHub 自动关闭;
114+
- 推送到特性分支不会关闭 issue;特性分支合并到 `dev` 后仍保持打开,待 `dev → main` 合并时自动关闭;
115+
- 如需提前关闭,必须由维护者确认后执行 `gh issue close <id>`,不得擅自关闭。
116+
117+
### 8. 推送后回复 issue
118+
119+
**前置条件:特性分支已推送到 GitHub**。未推送前只可说明「修复已提交到本地特性分支,待推送」,不得发布完成结论。
120+
121+
回复内容包含:
122+
123+
- 根因与最终方案(与步骤 3 的差异);
124+
- 变更文件/能力(新增公共 API、交互变化);
125+
- 验证结果(测试用例数、构建结果);
126+
- 推送分支与提交号、对应 PR/评审状态;
127+
- 升级/兼容提示(如有行为变更)。
128+
129+
## 禁止事项
130+
131+
- 不得向 `dev` / `main` 推送,不得在本地合并 `dev`(是否合并由人工决定);
132+
- 特性分支推送是标准步骤,但推送前必须确认远程分支名,避免误推;
133+
- 不得在主工作区(非 worktree)直接修改业务代码;
134+
- 不得跳过测试与编译验证;
135+
- 不得在特性分支推送前发布完成回复(定位回复不受此限);
136+
- 不得在代码未进入默认分支前擅自关闭 issue;
137+
- 不得用相对路径跨 package 引用(前端规范)。
138+
139+
## 检查清单
140+
141+
- [ ] issue 已读取并确认现状
142+
- [ ] 定位结论已在 issue 回复
143+
- [ ] worktree + 特性分支已创建(基于 `dev`)
144+
- [ ] 测试先行且全量通过,构建通过
145+
- [ ] 特性分支已推送到 GitHub(`dev` 未改动)
146+
- [ ] 提交信息包含 `Closes #<id>`
147+
- [ ] 推送后已在 issue 回复修复与验证结果

‎flow-frontend‎

Submodule flow-frontend updated 31 files

0 commit comments

Comments
 (0)