PD Spec Rebase vs Patch Strategy¶
概念概覽
差異類型¶
核心知識¶
差異類型¶
PD 規格 v0.0.20 存在兩類問題： 1. 缺漏：完全沒有 Sticker 模組（11 個 user-facing codes 5001-5031 未記載） 2. 語意錯誤：如 error 2032 描述為「非法字元」但實際語意是「長度限制」
Rebase 策略¶
當規格與實作差距過大時，建議 PD 以 TODO_pd_error_code_translation.md 為基準**重新對齊**（rebase），而非在舊規格上逐條 patch。Patch 策略在差距大時會造成：
- 遺漏項目增加
- 語意錯誤累積
- 版本衝突難以追蹤
TODO_ 前綴豁免機制¶
TODO_ 前綴的文檔可豁免 check-doc-metadata.ps1 lint 檢查，適合用於進行中的過渡文件（如 TODO_pd_error_code_translation.md）。
經驗教訓¶
-
PD 規格落後實作是常態，但語意錯誤（而非僅缺漏）代表規格完全脫鉤，需要 rebase 而非 patch
-
TODO_ 前綴是文檔治理的豁免機制，可用於標記尚未就緒的過渡文件
常見陷阱¶
-
在已有語意錯誤的舊規格上 patch 會導致錯誤訊息描述不符，用戶看到誤導性文字
-
PD 規格缺漏整個模組（Sticker）代表雙方溝通斷層，不只是文檔問題
最佳實踐¶
-
規格差距評估：缺漏 < 30% 可 patch；超過或有語意錯誤應 rebase
-
以工程端的 TODO_ 翻譯文件作為 PD rebase 的 single source of truth
相關概念¶
- Document Governance Phase Classification
- Docs Governance Superseded Pattern
- Error Code Range Collision
- Twirp Error Code Single Channel Architecture
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-07 | 13536126-c4f1-4c71-ae73-a6544e9167bf | 識別 PD 規格 v0.0.20 與實際設計的結構性差異，建立「rebase 優於 patch」的文檔對齊策略 |