4f8ee0a8c5
按项目方给的规则重做 CHANGELOG 与检查器(本轮不推、不打 tag、不部署): - 条目形状:四个自定义必填节(改了什么/兼容性与迁移影响/怎么验收/已知问题) → 固定四类 Added/Changed/Fixed/Security;分类可省略,**不许空栏目**;每个版本块 至少一个非空分类;`[Unreleased]` 段不得写日期。 - 破坏性变化:固定写在 Changed 里、以 `**破坏性**` 开头,**必须链接发布文档**; 仓内 `docs/….md` 链接**对账**(不存在 ⇒ 红)。写在别的分类里也判红。 - 结构判据补强:非法日期、重复版本、顺序必须严格递减、前导零;围栏代码块里的 `##`/`###` 不算标题;**块正文以任意二级标题为界**(「## 能力基线(未发布)」这类 不带方括号的标题原先不是边界,会把后文算成上一节的内容 ⇒ 空栏目被兜成"有内容", 夹具真的抓到了这个假绿)。 - tag 一致性:远端专属清单 `.ci-remote-tags` → `ls-remote` → 本地 refs 三级来源; **没核对远端就不许说校验成功**(CI/预检用 `--require-remote`,拿不到清单即红), 非正式 tag(如本地 `x`)不当作发布版本、不判红,没有 tag 不判红。 - `0.1.0` 定为**未发布的能力基线**(远端无 tag、无 Release):改成不带方括号的 「## 能力基线(未发布)」,不补造 tag/发布日期/发布事实。 - 过程记录迁出:审查轮次与命令输出 → `docs/archive/CI_接入留档.md`(原文保留); 未合并事项 → `docs/BACKLOG.md`;补 `docs/RELEASE_RUNBOOK.md`(破坏性变化的链接目标, 同时修掉 CHANGELOG 里指向不存在文档的悬空引用)。 - 发版预检:无版本基线时把「首个正式版本号由人指定」列成阻塞项(不再要求先有基线才能跑); 打印破坏性变化条数;远端 tag 查不到时明说未核对并阻塞;不再硬读已删除的『已知问题』节。 - traps trap-5 口径修正:不是"不用 tag",而是"构建时不要用 git describe 取版本号"。 验证:check_changelog --self-test 全过;反仓夹具 80/0(含五条真改文件的结构负例、 六条只在临时仓库里造 tag 的场景);make verify 15/15 success。
57 lines
3.6 KiB
Markdown
57 lines
3.6 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`
|
||
—— 它只列事实(候选版本 / 完整 SHA / 该提交的 CI 证据 / `[Unreleased]` 原文 / 远端同名 tag 与
|
||
Release 是否已存在 / 遗留风险),有阻塞项就**不给**"可以发"的结论。
|
||
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`);普通 `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"。 |