7a9d51cc70
按要求补三项(本轮不推、不打真实 tag、不部署;全部用临时仓库与假对象验):
1) 正式构建身份不能只认 --release:
- 新增 release_evidence():核①完整 40 位 SHA ②**指向该提交的注释 tag** v<版本号>
③该提交里 CHANGELOG 顶部版本一致。缺任一条 ⇒ rc=2,身份退回 development 并把
release_blocked 的原因写进 JSON(给机器读,也给人看)。
- version.py --self-test:六条负例(有版本无 tag / unknown SHA / 短 SHA / tag 指错提交 /
轻量 tag / 版本不一致)+ 证据齐正例,**tag 全部在 mktemp 临时仓库里创建**。
- Go 侧新增 TestReleaseBuildRequiresEvidence:release 构建必须 CommitSHA 完整且
v<ReleaseVersion> 是**注释 tag** 并指向该提交(独立于 Python 的二次复核)。
2) 发布预检区分"准备建议"与"发布就绪":
- 新增纯函数 readiness(facts) → (是否就绪, 阻塞项, 建议);输出分两段。
- **就绪要求候选版本已写进目标提交**(version_in_commit:查 git show <sha>:CHANGELOG.md,
工作区写了没提交不算);首发按**显式指定版本**处理,**不把"记录里有这个版本"当已发布**
(已发布的证据是 tag,不是记录条目)。
- 预检**不执行、也不在输出里推荐自动发布路径**(正式发版由人按 docs/RELEASE_RUNBOOK.md)。
3) CI 就绪判据:必需 context 集合来自 .gitea/required-contexts.txt(缺失/为空 ⇒ 没有策略 ⇒
阻断,不用观察到的状态顶替);**全部 success 才通过**,失败/缺项/pending/查询异常一律阻断。
Release 查询加 release_state():**只有 HTTP 404 才算不存在**,403/5xx/超时算查询异常 ⇒ 阻断。
验证:version.py --self-test 绿;release_preflight --self-test 绿(就绪判定 19 个分支 +
临时仓库验证 git show 语义 + 五个 HTTP 码语义);go test 三态(未注入 SKIP / 开发 PASS /
自称正式 RED);反向夹具 83/0(含临时仓库 go test 六例、预检"记录未进提交"两态);
make verify 15/15 success。
73 lines
4.9 KiB
Markdown
73 lines
4.9 KiB
Markdown
# 发布说明(正式版本)
|
||
|
||
> 这份文档是**破坏性变化与数据迁移步骤的落脚点**:`CHANGELOG.md` 里以 `**破坏性**` 开头的条目
|
||
> **必须**链接到本文(或本文的某个小节)。发布记录本身仍在 `CHANGELOG.md` —— 本文不维护第二份变更列表。
|
||
>
|
||
> 本仓 CI **只做 CI**:不打 tag、不发 Release、不部署。发布与部署都是**独立的人工审批动作**。
|
||
|
||
## 一、正式发布(由人批准后执行)
|
||
|
||
1. **确认基线**:`git rev-parse HEAD` 拿到完整 40 位 SHA,工作区干净(`git status --porcelain` 为空)。
|
||
2. **写记录**:把这次要发的东西从 `[Unreleased]` 提到一个正式版本条目
|
||
`## [x.y.z] - YYYY-MM-DD`(四类小节,无空栏目;破坏性变化写在 `### Changed` 里并链接本文)。
|
||
版本号**只增不减**(回退走部署层,不改这个文件);每个项目只有本文件这一个版本来源。
|
||
3. **跑预检(只读)**:`python3 scripts/release_preflight.py --version X.Y.Z`
|
||
—— 输出**两段**:`准备建议`(还差什么)与 `发布就绪判定`(是否就绪)。
|
||
⚠️ 预检**不执行、也不推荐自动发布路径**;正式发版动作由人按本文执行。
|
||
**就绪 = 证据齐(缺一条都不算)**:
|
||
|
||
| 判据 | 说明 |
|
||
|---|---|
|
||
| 候选版本**已写进目标提交** | 查 `git show <sha>:CHANGELOG.md`;只在工作区写了、没提交 ⇒ 不就绪 |
|
||
| 完整 40 位 SHA 指向准确提交 | 目标提交 == HEAD,或 `--sha` 逐字符一致 |
|
||
| 记录检查通过 | 结构与 tag 一致性(真查远端) |
|
||
| **必需 context 集合全部 success** | 集合来自 `.gitea/required-contexts.txt`;缺失/为空 ⇒ 没有策略 ⇒ 阻断;失败 / 缺项 / pending / 查询异常一律阻断 |
|
||
| 远端 tag 已核对且未被占用 | 查不到远端 ⇒ 阻断 |
|
||
| Release 不存在 | **只有 HTTP 404 才算「不存在」**;403/5xx/超时 ⇒ 查询异常 ⇒ 阻断 |
|
||
| 首发版本号 | 还没有已发布版本 ⇒ 必须**显式指定**;**不把「记录里有这个版本」当作已发布** |
|
||
|
||
自查(不依赖网络、不打真 tag):`python3 scripts/release_preflight.py --self-test`、
|
||
`python3 scripts/version.py --self-test`。
|
||
4. **批准后执行**:`python3 scripts/release_preflight.py --execute --version X.Y.Z
|
||
--approve-version X.Y.Z --approve-sha <完整SHA>`(两个批准参数必须逐字符等于预检结果)。
|
||
它创建**注释 tag** `vX.Y.Z`(指向验收过的那个提交)并建关联 Release,正文取自 `CHANGELOG.md`。
|
||
5. **读回**:`git ls-remote --tags origin` 里该 tag 的 SHA == 本地 `git rev-parse vX.Y.Z^{commit}`;
|
||
Release 的 `tag_name` 正确。**已发布的 tag 不移动、不覆盖。**
|
||
|
||
⚠️ 三个状态分开说:**CI 成功 ≠ 正式发版 ≠ 已部署**。
|
||
|
||
## 二、构建身份怎么看
|
||
|
||
```bash
|
||
python3 scripts/version.py --identity # JSON:release_version / build_kind / commit_sha / display_version / built_at
|
||
```
|
||
|
||
| 情形 | `build_kind` | `release_version` | `display_version` |
|
||
|---|---|---|---|
|
||
| 普通开发构建(有正式基线) | `development` | 顶部已发布版本 | `X.Y.Z-dev+g<短SHA>` |
|
||
| 普通开发构建(**还没有正式版本**) | `development` | `null` | `dev+g<短SHA>` |
|
||
| 发布构建(显式给出发布上下文) | `release` | 顶部已发布版本 | `X.Y.Z`(另带完整 SHA) |
|
||
|
||
- `build_kind=release` **只能**来自显式的发布上下文(`BUILD_KIND=release`),并且**要核证据**:
|
||
完整 40 位 SHA + **指向该提交的注释 tag** `v<版本号>` + 该提交里 CHANGELOG 顶部版本一致;
|
||
缺任何一条 ⇒ **拒绝标为正式版**(`--identity --release` 以 rc=2 退出、身份退回 `development`
|
||
并列出缺什么)。普通 `main` CI 永远是 `development`,**不得**因为"CHANGELOG 顶部有版本号"就自称正式版。
|
||
- 二进制里的注入字段(`internal/version`)与上表一一对应;契约测试断言:
|
||
注入 == CHANGELOG 顶部(发布构建)、开发构建必须是 `dev` 形状(**不许声称正式版**),且**跳过不算通过**。
|
||
|
||
## 三、破坏性变化 / 数据迁移怎么写
|
||
|
||
在 `CHANGELOG.md` 的 `### Changed` 里:
|
||
|
||
```markdown
|
||
- **破坏性**:接口 `/api/old` 下线,升级步骤见 [迁移步骤](docs/RELEASE_RUNBOOK.md#三破坏性变化--数据迁移怎么写)
|
||
```
|
||
|
||
要求:**必须以 `**破坏性**` 开头**(便于发版前扫出来)、**必须带本文链接**;仓内相对链接会被
|
||
`scripts/check_changelog.py` **对账**(文件不存在 ⇒ 红)。迁移步骤要写清「先做什么、怎么验证、怎么回退」。
|
||
|
||
## 四、回滚
|
||
|
||
回滚**不改** `CHANGELOG.md`、**不动** tag:走部署层(恢复上一个已验收的镜像/版本 + 读回证据)。
|
||
本仓部署流程在 `docs/OPERATIONS_RUNBOOK.md` 与各环境的部署脚本里;部署是**独立审批**,
|
||
并要记录"实际部署的版本 + 完整 SHA"。 |