From 1bcfe444c654dc6b50fce66b2b42e511764b39cc Mon Sep 17 00:00:00 2001 From: Lixi20 Date: Thu, 10 Sep 2026 16:16:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E8=AE=B0=20v0.3.0=20=E5=88=86?= =?UTF-8?q?=E6=94=AF=E4=BF=9D=E6=8A=A4=E5=AE=9E=E9=85=8D=E4=B8=8E=E5=90=8E?= =?UTF-8?q?=E7=BB=AD=E5=8F=91=E5=B8=83=E6=B5=81=E7=A8=8B=E5=8F=98=E6=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - checklist 第 6 步执行记录：api/flutter 的 main 已保护（经 Gitea API 核实 protected=true、禁直推、状态检查上下文显式填写），dev 保持直推流 - 说明状态检查上下文为何显式填写而非留空（留空时空集为真会反而放行） - ⚠️ 明确后续发布姿势变更：main 禁直推后，dev→main 须走 PR + CI 门禁， 首次发布用的直推写法仅适用于保护启用前；checklist 第 4 步相应作废 Co-Authored-By: Claude Fable 5 --- docs/development/releases.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) 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 改动过,**先查明原因再合并**,不要用合并提交掩盖。