diff --git a/docs/development/releases.md b/docs/development/releases.md index 193a70a..6671191 100644 --- a/docs/development/releases.md +++ b/docs/development/releases.md @@ -44,7 +44,16 @@ 1. **命名统一**:ADR-011 的 `master` 更正为 `main`(ADR-021);api 本地孤儿 master 已删。 2. **api main 重建**(方案 A,用户拍板):远端 main 原为建仓自动生成的单提交 `ff876bc "Add README"`,与 dev **无共同祖先**,无法 ff 也不宜缝合孤儿历史。操作:Gitea 默认分支临时切 dev → 删除远端 main → `git push origin dev:refs/heads/main` 重建 → 默认分支切回 main。结果:main 41 提交、与 dev 同点位、零 force push。原孤儿提交保留本地备份 ref `refs/backup/old-main-ff876bc`。 -3. **flutter main 快进**:main 本就是 dev 祖先,用 `git push origin dev:main` 完成——**较 checklist 第 4 步的 `checkout main && merge --ff-only` 改进**:不切换工作区(当时有 E2E 脚本正在该工作区运行),且非快进推送会被 git 自动拒绝,等于内建 ff-only 保护。建议固化此写法。 +3. **flutter main 快进**:main 本就是 dev 祖先,用 `git push origin dev:main` 完成——**较 checklist 第 4 步的 `checkout main && merge --ff-only` 改进**:不切换工作区(当时有 E2E 脚本正在该工作区运行),且非快进推送会被 git 自动拒绝,等于内建 ff-only 保护。 +4. **分支保护启用**(checklist 第 6 步,Gitea 平台):api 与 flutter 的 `main` 均已启用,经 Gitea API `GET /repos/{owner}/{repo}/branches/main` 核实: + + | 仓库 | protected | 推送 | 状态检查上下文 | 所需批准 | + | --- | --- | --- | --- | --- | + | patbond-api | `true` | 禁用直接推送 | `CI / backend-test (push)` | 0 | + | patbond-flutter | `true` | 禁用直接推送 | `CI / flutter-gates (push)` | 0 | + | patbond-doc | 未启用 | —— | —— | —— | + + 两仓 `dev` 均保持 `protected=false`(直推流,ADR-021 分层策略);doc 仓 main 即日常分支、不参与发布分支语义,按规划不设保护。**状态检查上下文显式填写而非留空**:留空时 Gitea 语义为「所有上报的检查都通过」,若某次工作流未触发则空集为真反而放行;写死检查名消除该歧义。 ### 已知遗留(不阻塞发布) @@ -56,6 +65,14 @@ ### 发布后生效的纪律 -- 影响 `main` 的 hotfix 一律走短命分支 + PR(ADR-021 强制情形之二正式生效) -- `main` 分支保护(禁直推、合并需 CI 状态检查通过)在 Gitea 平台启用;`dev` 保持直推流 -- 下次发布 `dev → main` 应能 `--ff-only` 通过;过不了说明 main 被绕过 dev 改动,先查明原因 +- **`main` 已禁止直接推送**——影响 `main` 的一切变更(含发布本身与 hotfix)一律走 PR,CI 状态检查通过方可合并(ADR-021 强制情形之二正式生效)。`dev` 保持直推流不变。 +- **⚠️ 下次发布的姿势与本次不同**:本次首发用 `git push origin dev:main` 直推(当时 main 尚未保护);保护启用后该命令会被拒绝。**此后发布流程为**: + + 1. 完成 checklist 第 1~2 步(三仓 CI 绿 + E2E 双份回归 PASS); + 2. 在 Gitea 上创建 PR:`dev` → `main`(标题写版本号,正文贴门禁证据链接); + 3. 等 PR 的 CI 状态检查转绿(即上表的 `status_check_contexts`); + 4. 在 Gitea 上合并 PR——因 dev 与 main 无分叉,合并应为快进; + 5. 继续 checklist 第 5、7 步(打 tag、写本页记录)。 + + 故 checklist 第 4 步的本地 `merge --ff-only && push` 写法**仅适用于首次发布**(保护启用前),后续版本以上述 PR 流程替代;第 3、6 步为一次性项,不再重复。 +- 若某次 PR 显示 `dev` 与 `main` 有分叉(无法快进),说明 main 被绕过 dev 改动过,**先查明原因再合并**,不要用合并提交掩盖。