发布列车与版本节奏治理

随到随发（Continuous Deployment）成立的前提：
  1. 单个服务独立部署，无跨服务协同
  2. 有完善的自动化测试与灰度能力
  3. 下游对上游的变更「无感」（向后兼容做得好）
  4. 组织上不需要「同步发布窗口」

一旦出现「多个组件必须一起升级」「下游需要验收」「需要运维值守」，
随到随发就会把协调成本转嫁给每一个参与方。

发布列车解决的问题：
  - 可预期：所有人知道下一班车什么时候发
  - 可协调：测试、运维、下游能提前安排
  - 可批量：多个变更一起验证，摊薄验证成本
  - 可回退：一个版本对应一个可回滚的边界

代价：
  - 变更要「赶车」，错过就等下一班（引入等待）
  - 列车本身可能成为瓶颈，需要足够的发车频率

时刻表（Schedule）：多久发一班车（每周、双周、每月）
车次（Train）：一次具体发布，有唯一版本号
车厢（Car）：每个变更（PR/特性）是挂到车次上的一节车厢

一个两周列车的典型时间线（以周五发车为例）：
  D-10  车次开启，特性开始「挂车厢」
  D-3   车厢截止（Cut-off），此后的变更进下一班
  D-3~D-1 冻结窗口：只允许修复阻断性问题
  D-0   发车：构建、签名、发布、部署
  D+1~D+3 观察期：监控、热修复通道开启

发车频率的权衡：
  太频繁（每天）：协调成本高，冻结窗口形同虚设
  太稀疏（每季度）：车厢积压，风险集中，错过一班损失大

常见选择：
  每周 / 双周：适合有客户端或平台组件的团队
  每月：适合强合规、需要完整验收周期的场景
  需求驱动：适合「车厢凑齐才发车」的批量交付

车厢准入清单：
  □ 代码已合并到主干（或发布分支）
  □ 单元/集成测试全绿
  □ 已通过代码评审
  □ 有变更说明（changelog 条目）
  □ 无未解决的阻断性缺陷
  □ 若涉及数据库变更，已确认向前/向后兼容

语义化版本（Semantic Versioning, SemVer）：MAJOR.MINOR.PATCH

适合：对外提供 API 或 SDK，使用者依赖版本号判断兼容性
不适合：纯内部服务、频繁发布的应用

误用：
  - 内部服务把「每次发车」都当 MINOR，版本号迅速膨胀到 4.x.300+
  - 为了「看起来稳定」长期不升 MAJOR，破坏性变更藏在 MINOR 里

日历版本（Calendar Versioning, CalVer）：用日期表达版本
  例：2026.10.1（年.月.第几次发布）
      2026.10.07（年.月.日）

优点：一眼看出新旧与发布时间，无需推断
缺点：无法表达「是否向后兼容」

适合：应用、平台、发行版（如 Ubuntu 24.04）
不适合：被下游按版本号解析兼容性的库

一套常见的三段式：
  对外版本（对外可见）：2.4.0        ← 业务/客户感知
  发布车次（内部）：2026-w41         ← 对应某周的列车
  构建号（唯一）：2.4.0+20261007.3  ← 每次构建唯一，可追溯

关键原则：
  - 构建号必须唯一且可追溯（对应某个 commit SHA）
  - 对外版本可重复使用（如 2.4.0 的多个构建），但要能区分
  - 版本号一旦发布不可复用（禁止覆盖已发布的制品）

反模式：版本号散落在 package.json、pom.xml、构建脚本、CI 变量里
  → 各处不一致，追溯困难

正模式：单一来源（single source of truth）
  - 从 git tag 派生版本号（推荐）
  - 或从集中版本文件读取，构建时注入所有产物

# 从 git tag 派生版本（tag: v2.4.0）
VERSION=$(git describe --tags --always --dirty)
# 输出示例：v2.4.0 或 v2.4.0-12-gabc1234（距 tag 12 个提交）

# 写入构建产物
echo "{\"version\":\"${VERSION}\"}" > dist/version.json

主干开发 + 发布分支：
  main ──●──●──●──●──●──●──●──●──►   （持续开发）
          \                    \
           release/2.4 ──●──●──●   （发车后冻结，只接受热修复）
                              \
                               hotfix/2.4.1 ──●  （紧急修复）

规则：
  - 发车前从 main 切出 release/<version>
  - release 分支只接受 bugfix，不接受新特性
  - 修复要「双向合并」：既回 release，也回 main，避免下次发车重现
  - 版本 tag 打在 release 分支上

热修复的准入：
  - 生产环境出现阻断性故障或安全漏洞
  - 修复范围最小化（只改必要代码）
  - 由值班主责人或发布负责人批准
  - 修复后必须补上回归测试
  - 必须双向合并回 main

不允许：
  - 借热修复通道夹带新功能
  - 未经测试直接上线（即使是「一行修复」）

# 发车时的标签与制品
git checkout release/2.4
git tag -a v2.4.0 -m "Release 2.4.0 (train 2026-w41)"
git push origin v2.4.0

# 触发发布流水线（通常由 tag 触发）
# 见 .github/workflows/release.yml

冻结（Freeze）不是「停止一切变更」，而是「限制变更类型」：

  完全冻结：只允许修复阻断性缺陷（发车当天）
  软冻结：允许修复类变更，需评审（发车前 1~2 天）
  发布冻结：发车后到观察期结束，仅热修复
  业务冻结：大促、节假日期间，禁止非必要发布

# .github/workflows/freeze-check.yml
name: freeze-check
on:
  pull_request:
    branches: [release/*]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Enforce freeze policy
        run: |
          if [ -f .freeze ]; then
            echo "当前处于冻结窗口，仅允许 hotfix/* 分支合入"
            if [[ "${{ github.head_ref }}" != hotfix/* ]]; then
              echo "::error::冻结期间禁止合入非热修复变更"
              exit 1
            fi
          fi

冻结窗口越长，列车的交付能力越弱：
  两周列车 + 3 天冻结 → 有效开发窗口只有 11 天
  频繁冻结 → 开发者习惯「赶在冻结前塞变更」→ 发车日风险集中

缓解：
  - 冻结窗口尽量短（软冻结用自动化替代人工评审）
  - 用特性开关（Feature Flag）把「合并」与「启用」解耦
  - 把高风险变更安排在列车早期，而非截止前

列车模型下，相邻车次之间应保持兼容：
  数据层面：新版本写入的数据，旧版本能读（否则回滚即数据损坏）
  接口层面：新增字段可选，不删除/不改语义
  配置层面：新配置项有默认值，旧配置不失效

「向前兼容 + 向后兼容」是回滚能力的前提。

回滚的三个层级：
  1. 应用回滚：切回上一个版本镜像/tag（最快）
  2. 配置回滚：切回旧配置（注意配置与版本的匹配）
  3. 数据回滚：最难，通常靠「向前修复」而非「回退数据」

关键：回滚必须经过演练。
  没演练过的回滚 = 没有回滚。

节奏类：
  - 发车准点率（实际发车时间 vs 计划）—— 目标 > 90%
  - 车次间隔的稳定性（标准差越小越好）

质量类：
  - 每个车次的变更失败率（发车后触发回滚/热修复的比例）
  - 车次平均车厢数（过多说明积压，过少说明频率过高）
  - 热修复频率（频繁说明准入或测试有问题）

效率类：
  - 变更从合并到发车的等待时长（列车引入的额外延迟）
  - 车厢截止前的变更占比（越集中越危险）

发布列车的价值不在「发得少」，而在「发得准」：
  稳定的节奏 + 明确的准入 + 可靠的回滚 = 可预期的交付。