破坏性变更流程

安全发破坏性变更的端到端流程 — 从决策到 sunset 到删除。

为什么

破坏性变更是团队最具客户影响的决策，故需防两失败模式的流程：草率发（坏客户端）和永不发（代码库腐烂）。流程是：论证（破坏值得成本？）、版本化（semver major）、弃用（信号 + sunset）、迁移（提供路径 + codemod）、沟通（多渠道）、监控（用量 %）、然后删除（仅标准达后）。每步有门控阻止前置不满足时继续 — 如用量 <1% 持续 30 天前不可删。这把可怕的一次性变可重复清单。

何时使用

每次破坏性变更。流程即门控 — 无破坏性变更过每步前不发。

如何做

1. 论证：写一段为何破坏值得迁移成本的论证（链决策文档）
2. 版本化：破坏在新 major（semver）中发；旧 major 带弃用信号续工作
3. 弃用：加 Deprecation + Sunset 头、@deprecated JSDoc、console.warn、changelog "弃用"节
4. 迁移：写 docs/migrate-<旧>-<新>.md 含前后 + 行为 diff + codemod
5. 沟通：changelog + 邮件 top 调用者 + 博客 + 弃用仪表盘
6. 监控：跟踪弃用物用量 %；不降则告警
7. 删除：仅 (a) sunset 日期过 且 (b) 用量 <1% 持续 30 天后；发 410 Gone + Link
8. 复盘：有客户端坏吗？若有，哪个沟通渠道失败 — 下次修它

示例

# BREAKING_CHANGE.md（模板，每变更填）
## 变更：/v1/orders 响应形状
### 1. 论证
v1 的 { items, total } 包装冗余；v2 直接返数组并把 total 放头。
这简化 90% 客户端代码。对用包装的 10% 值迁移成本。

### 2. 版本化
在 v2（semver major）中发。v1 带弃用信号续工作。

### 3-5. 弃用 + 迁移 + 沟通
- 头：每 /v1 响应带 Deprecation + Sunset + Link
- 指南：docs/migrate-v1-v2.md（前后 + codemod）
- 邮件：top 100 /v1 调用者，个性化带其用量数
- 博客："v2 即将破坏性变更"（2024-06-01）

### 6. 监控（仪表盘）
| 日期       | v1 用量 | v2 用量 |
|------------|---------|---------|
| 2024-06-01 | 100%    | 0%      |
| 2024-09-01 | 45%     | 55%     |
| 2024-12-01 | 0.8%    | 99.2%   | <- 可删！

### 7. 删除（2024-12-15）
# v1 返 410 Gone + Link 到 v2
# （用量 <1% 持续 30 天，sunset 日期过）

常见问题

⚠跳论证步 — "因更干净"的破坏性变更因审美偏好坏客户端。
⚠用量标准未达即删 — 你到 sunset 日期就删，坏仍用它的 5%。
⚠客户端坏后无复盘 — 同沟通缺口在下个破坏性变更重复。

最佳实践

✓把流程做带门控清单 — 前门控过前不进下步；这防截止压力下走捷径。
✓每破坏性变更要求书面论证 — 若你说不清为何值得客户端成本则不值得。
✓任一客户端坏则复盘 — 流程某处失败，修的是流程非仅此变更。