API Refactoring PR Splitting Strategy

概念概覽

核心原則：API 簽名與語義必須分 PR

核心知識

核心原則：API 簽名與語義必須分 PR

將「API footgun removal（compile-time breaking）」與「outcome semantics 變更（runtime behavior）」混在同一個 PR，會讓 reviewer 無法正確評估風險，也可能讓語義變更被 API cleanup 偷渡。

PR1（API Cleanup）： - 移除/重命名有問題的 API 簽名 - 是 compile-time breaking change，但 runtime 行為不變 - PR 描述應寫：「compile-time breaking API change，低 runtime 風險」 - 不要寫「zero risk」——這會誤導 reviewer 跳過仔細審查

PR2（Semantic Change）： - 基於 PR1 merge 後才開工 - 改變 outcome 語義（如 tri-state 引入、context 錯誤分類） - 需要更嚴格的 review，因為影響 runtime 行為

PR 描述措辭的重要性

❌ 錯誤：「zero risk change」
✅ 正確：「compile-time breaking API change；低 runtime 風險，高可編譯性可驗證」

這個區別讓 reviewer 知道：API 層面有破壞性，但可以靠編譯器驗證所有呼叫點都已更新，runtime 行為不變。

經驗教訓

• API 簽名重構與行為語義變更混在同一 PR 會讓 reviewer 無法正確評估，必須嚴格拆分

• PR 描述中「zero risk」是不精確且有害的表述，應改為說明具體的風險類型（compile-time vs runtime）

常見陷阱

• 在 PR1（API cleanup）尚未 merge 時就開始 PR2（semantic change），導致兩個 PR 相互依賴難以 review

• 用「zero risk」描述 compile-time breaking change，讓 reviewer 誤以為不需要仔細審查

最佳實踐

• PR 描述明確標注變更類型：compile-time breaking、runtime behavior change、refactor only

• 語義變更的 PR 必須等 API cleanup PR merge 且 CI 通過後才開工

相關概念

• Circuit Breaker Outcome Semantics
• Go Middleware Chain Ordering

相關視角

以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：

• Proto Delivery Boundary Design — 共享：api-design / 獨特：breaking-change-prevention, csharp

來源 Sessions

日期	Session	貢獻摘要

| 2026-03-26 | 59325dc8-0079-4c87-a93e-f2734386d733 | 建立了將 compile-time breaking API change 與 runtime semantic change 強制拆分成獨立 PR 的原則，以及 PR 描述的正確措辭 |

---

本概念頁面由 Semi-Brain Wiki 系統自動維護

最後更新: 2026-03-26