| name | workflow/github-issue |
|---|---|
| module | workflow |
| description | GitHub Issue 标准处理流程 — 定位 → 回复 → worktree 修复 → 推送特性分支 → 推送后回复(8.x/17.x 双线) |
| status | 已实现 |
| scope | 全栈 |
| source | 项目自有 |
不遵守此流程会导致:
- 问题分析结论只留在本地,issue 参与者无法同步进展
- 直接在主干工作区改代码,污染工作区、难以回滚和并行处理多个 issue
- 只修了一条版本线就声称修复完成,另一条线(8.x 或 17.x)漏修
- 修复完成后 issue 长期悬空,无法追溯「哪个提交解决了哪个 issue」
- 分支、worktree、合并目标不统一,发布时遗漏改动
codingapi/springboot-framework 仓库的所有 GitHub issue。本仓库同时维护两条版本线,issue 可能落在任意一条上:
| 版本线 | 技术栈 | 模块 | 发布路径 |
|---|---|---|---|
| 17.x | JDK 17 / Spring Boot 3.x,jakarta.* |
5 个 starter + example/ + frontend/(PC 端、移动端) |
17.3.x → main |
| 8.x | JDK 8 / Spring Boot 2.7.x,javax.* |
5 个 starter,无 example/、无 frontend/ |
8.2.x 独立发布 |
两条版本线功能基本一致,但 API 命名空间不同(jakarta vs javax)、JDK 与 Spring Boot 代际不同,代码不能直接照搬。
| 分支 | 用途 |
|---|---|
main |
默认分支,17.x 系列的发布分支;17.3.x 通过 PR 合入后打 v17.3.x 标签 |
17.3.x |
17.x 版本开发分支,17.x issue 的基线与 PR 目标 |
8.2.x |
8.x 版本维护分支,8.x issue 的基线与 PR 目标,独立打 v8.2.x 标签发布 |
2.x |
历史版本分支,仅在 issue 明确指向 2.x 时使用 |
本仓库没有
dev分支,也没有「统一开发分支」的概念:每条版本线各自维护、各自交付。仓库中残留的dev分支为历史遗留,已废弃,不得作为基线或交付目标。
- 分析可以不开 worktree,改代码必须开:定位阶段只读代码即可;一旦确定要修改,必须新建 git worktree + 特性分支。
- 先定版本线,再动手:定位阶段必须确认 issue 属于 8.x、17.x 还是两者,并按对应版本分支创建 worktree。
- 先回复,再动手:定位到问题后,先在对应 issue 回复根因、影响版本与处理方案。
- 版本分支只作基线,不参与交付:worktree 基于
17.3.x或8.2.x创建;修复提交、推送与 issue 关联全部发生在该 issue 的特性分支上。完成后不合并版本分支,是否合并由人工决定,助手只在任务完成时提示分支与 PR 链接。 - 双版本 issue 必须双线验证:同时影响两条线时,两条线各切一个特性分支、各自测试、各自推送,不得只修一条线就宣布完成。
- 提交即关联 issue:提交信息使用
Closes #<id>关联;是否已真正关闭取决于是否进入默认分支main,未自动关闭时由维护者确认后手动关闭。 - 推送后再回复:特性分支推送到 GitHub 之后,才在 issue 回复修复内容、提交与验证结果;未推送前不得发布完成回复。
gh issue view <id> --repo codingapi/springboot-framework \
--json number,title,state,labels,body,comments,author,createdAt- 使用代码搜索、LSP、文档(
docs/conventions、docs/capabilities)定位根因; - 判定版本线:issue 的复现环境、依赖坐标(
17.3.x/8.2.x)、报错栈中的jakarta.*或javax.*都是判断依据;无法判断时按 17.x 处理,并在定位回复中请提问者确认是否需要同步 8.x; - 明确影响模块(哪个 starter /
example/frontend的 PC 端或移动端); - 判断是否属于已有能力缺陷,优先复用既有能力(统一响应
Response、动态查询PageRequest+FastRepository、事件EventPusher、数据权限 SQL 拦截等),而不是新增一套实现。
将以下内容整理为中文评论:
- 问题原因(引用具体类/文件/方法);
- 影响版本线(8.x / 17.x / 两者)及判断依据;
- 处理方案(改动点、行为变化、兼容性;双版本时说明两条线的差异点);
- 交付方式(基于对应版本分支的特性分支名,完成后由维护者合并)。
gh issue comment <id> --repo codingapi/springboot-framework --body-file /tmp/issue-<id>-analysis.md.worktrees/ 已被 .gitignore 忽略。按版本线二选一;双版本则两条都建:
# 17.x
git worktree add .worktrees/issue-<id>-17x -b feature/issue-<id>-<slug>-17x 17.3.x
# 8.x
git worktree add .worktrees/issue-<id>-8x -b feature/issue-<id>-<slug>-8x 8.2.x- 分支命名统一带版本线后缀:
feature/issue-<issue编号>-<简短英文描述>-<17x|8x>,避免两条线同名冲突; - 17.x 的前端改动在同一 worktree 的
frontend/目录内进行,首次使用需安装依赖(worktree 内没有node_modules):
cd frontend
pnpm install --frozen-lockfile --prefer-offlineworktree 仅以对应版本分支为基线;创建之后的所有提交、推送与 issue 关联都只发生在该特性分支上,版本分支不参与交付。
- 先补测试(红灯),再实现(绿灯),最后重构;
- 后端测试位于各模块
src/test/java,使用 JUnit 5,类名以Test结尾; - 编译/测试必须使用该版本线对应的 JDK:17.x 用 JDK 17,8.x 用 JDK 8;
- 后端验证:
./mvnw test -pl <module> -Dtest=XxxTest;改动公共模块或被依赖模块后执行./mvnw clean install;提交前执行./mvnw clean test -P travis(与 CI 一致); - 前端验证(仅 17.x,在
frontend/下):pnpm test:pc/pnpm test:mobile、pnpm build:pc/pnpm build:mobile; - 8.x 分支没有
example/与frontend/,验证只覆盖后端模块,新增代码使用javax.*; - 修改代码后必须本地编译/测试通过,失败项如实报告,不得声称已验证;双版本 issue 必须在两条线各自的 worktree 中分别验证。
git push -u origin feature/issue-<id>-<slug>-17x # 17.x
git push -u origin feature/issue-<id>-<slug>-8x # 8.x- 只推送该 issue 的特性分支,
17.3.x/8.2.x保持不动,是否合并由人工决定; - 禁止推送到
17.3.x/8.2.x/main/dev,禁止在本地合并; - 任务完成提示中给出分支地址与 PR 链接(PR 目标分支:17.x →
17.3.x,8.x →8.2.x,不指向main),不代为合并; - 双版本 issue 需要两个 PR,分别对应两条版本线;
- 推送后可清理本地 worktree(
git worktree remove <path>),分支保留。
提交信息格式:
fix: <一句话描述> (<版本线>/<关联模块>)
<可选的改动说明>
Closes #<id>
Closes #<id>只在提交进入默认分支(main)时由 GitHub 自动关闭,即只有 17.x 经17.3.x → main合并时才可能自动关闭;- 8.x 的特性分支合入
8.2.x不会关闭 issue;仅修 8.x 的 issue 需在确认修复已发布后由维护者手动关闭; - 双版本同时修复时,17.x 提交写
Closes #<id>,8.x 提交写Ref #<id>,避免关闭语义重复; - 如需提前关闭,必须由维护者确认后执行
gh issue close <id>,不得擅自关闭。
前置条件:特性分支已推送到 GitHub。未推送前只可说明「修复已提交到本地特性分支,待推送」,不得发布完成结论。
回复内容包含:
- 根因与最终方案(与步骤 3 的差异);
- 变更文件/能力(新增公共 API、行为变化),双版本时按版本线分别列出;
- 验证结果(各版本线的测试用例数、构建结果、使用的 JDK);
- 推送分支与提交号、对应 PR/评审状态;
- 升级/兼容提示(如有行为变更);
- 未覆盖的版本线(若有),以及是否需要后续跟进。
- 不得向
17.3.x/8.2.x/main/dev推送,不得在本地合并(是否合并由人工决定); - 不得把 8.x 的修复直接 cherry-pick 到 17.x(或反向)而不做
javax↔jakarta、JDK / Spring Boot 代际适配; - 不得只修一条版本线就宣布双版本 issue 已修复;
- 特性分支推送是标准步骤,但推送前必须确认远程分支名,避免误推;
- 不得在主工作区(非 worktree)直接修改业务代码;
- 不得跳过测试与编译验证;
- 不得在特性分支推送前发布完成回复(定位回复不受此限);
- 不得在代码未进入默认分支前擅自关闭 issue;
- 前端 workspace 内跨 package 引用必须使用包名(
@springboot-framework/*),不得使用相对路径。
- issue 已读取并确认现状
- 已确认影响版本线(8.x / 17.x / 两者)
- 定位结论(含影响版本)已在 issue 回复
- worktree + 特性分支已创建(基于
17.3.x/8.2.x) - 测试先行且全量通过,构建通过(使用对应 JDK)
- 双版本 issue 已在两条线分别验证
- 特性分支已推送到 GitHub(版本分支未改动)
- 提交信息包含
Closes #<id>(双版本时 8.x 用Ref #<id>) - 推送后已在 issue 回复修复与验证结果