协作规范:Issue 生命周期 · PR 门禁 · 前后端联调 · 发版流程(MS4 起执行)

[minorcell]

背景

近期协作中暴露三类问题:

1. Issue 堆积:长期无跟进、PR 已合并但 Issue 未关、无 owner 无排期;
2. 前后端联调混乱:前端本地直连线上、后端接口变更无同步机制、未经 review 的代码直接上线;
3. 没有发版节奏:仓库至今 0 Tag / 0 Release。

本规范是项目组《GitHub 过程管理规范》《软件工程规范》在 Windup 仓库的落地细则——上位规范已强制要求 PR 必经 Review、每个 MS 发 Release + Tag、MS4 完成 v1.0 Tag,本规范只把它们落到可执行。

一、Issue 生命周期

• 每个 Issue 必须挂 milestone,并指定 owner(assignee);无 milestone 即不在计划内(现有 triage 自动挂载)。
• 关闭条件(满足其一即关,关闭时注明原因):① 已被 PR 解决(注明 PR 号);② 被其他 Issue 取代(注明替代者);③ 组内确认不再需要。
• MS3 收尾:MS3 时间界定上不延期。所有 MS3 遗留 Issue 在 MS4 创建后逐条归置:已完成的直接关闭;属于 MS4 打磨范围的挂入 MS4 并指定 owner;探索/契约类挂 MS4 或打 Proposal-NoPlan。由组长产出归置表贴在本 Issue 评论,全员当天对照补充。
• MS4 由组长根据 MS4 要求(功能冻结、打磨交付、v1.0 Tag)与本周周会结论创建。

二、PR 门禁

• 所有代码改动必须经 PR 合入 main，由 @nighca 或 @minorcell 或 @huyanxius 合并。
• 禁止把未经 review / 未合并的代码部署到生产环境,生产部署只认 Release(见四)。

三、前后端联调

• 前后端契约以一份自动生成的 OpenAPI 规格文件(根目录 openapi.json,由后端代码导出,禁止手写)为唯一契约源。后端 PR 变更接口时必须同步更新该文件,CI 校验漂移,否则不予合并。前端同学为后端 PR 的默认 reviewer 之一。
• 删除手维护的 frontend/API_CONTRACT.md(手动文档必然漂移),契约一律以 openapi.json 与 FastAPI /docs 为准。
• 前端联调一律走本地:后端 PR 合并后 git fetch upstream && git rebase upstream/main,本地启动后端服务与依赖容器(README 补充说明),Vite 指向本地 API(本周内补齐 .env.development + proxy)。
• 禁止本地开发直连生产 API。

四、发版流程

• 每个 MS 结束发一次 Release + Tag(上位规范,MS2 起执行);MS2/MS3 缺失的 Release 并入 MS4 最终版本。
• 过程中的生产部署同样必须先发版本:需要上线时,先打 Tag → 发 Release(写清变更内容)→ 再部署。任何部署只认 Release,禁止直接部署未发版的代码。
• 发布流程:main 通过验收 → 打 Tag vX.Y.Z → 创建 Release(列清变更)→ 由发布人执行部署。
• 生产部署暂为手动,由发布人唯一执行;CD 自动化另立 Issue 跟进(含 proposal: replace Vercel GitHub App deploys with Vercel CLI in GitHub Actions #298 Vercel CLI 改造)。
• MS4 最低交付含仓库 v1.0 Tag。

确认

请阅读后回复确认,有异议直接评论讨论;12 小时内无异议视为同意。敲定后本规范落地到根目录 CONTRIBUTING.md,本 Issue 置顶。

• @huyanxius
• @xyh202131
• @xiaocheny214
• @johnnyzhang-eng

[minorcell]

@huyanxius @xyh202131 @xiaocheny214 @johnnyzhang-eng

请各位查看本 Issue 的协作规范,有不懂或不同意见直接在下面讨论;确认无误请回复「确认」,或直接在本 Issue 正文勾选对应项。48 小时内无异议即视为生效,落地到 CONTRIBUTING.md。

另外两件今天的事:

1. 组长在周会后创建 MS4 milestone,并贴出 MS3 遗留 Issue 归置表(关闭 / 挂 MS4 / 暂不排期 + owner + 截止);
2. main 分支保护今天开启,此后所有改动必须走 PR + Review。

[minorcell]

@fennoai 请按本 Issue 第三节「前后端联调」的契约单源要求实现 OpenAPI 单源改造,完成后提 PR 即可:

1. backend/ 下新增 OpenAPI 导出脚本:加载 FastAPI 应用实例(backend/packages/app/src/windup_app/bootstrap/app.py 的 create_app),调用 app.openapi() 生成规格,序列化为仓库根目录 openapi.json(JSON 格式,不新增依赖;导出命令一行可跑,如 uv run python -m <脚本模块>)。
2. .github/workflows/backend.yml 增加契约漂移校验:重新运行导出并与提交的 openapi.json diff,不一致即 CI 失败。
3. 删除 frontend/API_CONTRACT.md,并清理全部引用:
   • README.md「相关文档」中的链接;
   • frontend/README.md 中的说明文字;
   • backend/tests/test_character_contract.py 与 backend/packages/common/src/windup_common/models/character.py 中引用该文件的注释(改为自包含说明,枚举取值与映射关系本身不变)。
4. 首次生成 openapi.json 后确认覆盖当前全部已挂载路由,backend CI 与测试全绿。

[fennoai]

已完成

已创建 PR #335 feat: establish generated OpenAPI contract。

• 新增 backend/scripts/export_openapi.py：cd backend && uv run python -m scripts.export_openapi 自动从 create_app() 生成根目录 openapi.json
• Backend CI 新增契约漂移校验，重新导出后通过 git diff --exit-code -- ../openapi.json 阻止漂移
• 删除 frontend/API_CONTRACT.md，清理 README 与角色契约注释中的全部旧引用
• 首次规格包含 23 个 API 路径，与当前全部挂载且纳入 schema 的路由完全一致；/health 与 FastAPI 文档端点按现有配置不纳入 schema

验证

• uv run ruff check .：通过
• uv run lint-imports：2 个契约通过
• uv run pytest -q --cov=packages --cov-report=term-missing --cov-report=xml:coverage.xml：673 passed，14 skipped
• 连续两次导出内容一致，CI 漂移命令通过

View job run

[johnnyzhang-eng]

确认。第一节依赖的 triage 自动挂载已在 #333 跟进，fennoai 的计划与根因一致，但在那个修复合入前新开的 issue 仍会漏挂——本 Issue 自己和 #330 #335 都是空 milestone，归置表最好等修完再拉，否则新开的还得再补一轮。MS3 遗留 issue 我名下最多，今天先自己过一遍出一份关闭／挂 MS4／不排期的清单贴上来，组长的表出来我按它对齐。

[xyh202131]

确认