SPECIFICATION

第 10 章版本管理

權威來源聲明（Single Source of Truth）。 DTP 版本管理的策略以第 1 章 §1.7「版本管理與相容性」為唯一權威來源。本章不得重新定義 §1.7 已規定的策略；本章僅提供 §1.7 規則的操作性機制（線格式綁定、錯誤碼具體載荷、協商時序、實作宣告範本）與治理流程（目錄與狀態約定、定稿標準動作）。本章任何陳述與 §1.7 發生歧義時，必須以 §1.7 為準。

10.1 版本號格式（操作性引用）

DTP 協定版本號的語義、MAJOR.MINOR 兩級結構（無 PATCH）、變更判定規則與正交軸定義見 §1.7.1 與 §1.7.2，本章不重述。

線格式綁定：每個 LogicalFrame 的訊框標頭必須攜帶完整的 ProtocolVersion 欄位（參見第 4.4 節）：

interface ProtocolVersion {
  major: number;  // 非負整數
  minor: number;  // 非負整數
}

本規範定義的協定初始版本必須為 { major: 1, minor: 0 }（即 dtp/1.0）。

10.2 版本相容性矩陣（§1.7.3 的操作性補充）

相容性與協商的規範性規則見 §1.7.3。下表為其在訊框處理層面的操作性落地，必須依據 §1.7.3 解讀，二者如有歧義以 §1.7.3 為準。

接收訊框版本	處理方式
等於接收方最高版本	正常處理
等於接收方最高版本的前一個主版本（major - 1）	相容處理（按舊規範處理）
高於接收方最高版本	必須返回 `VERSION_INCOMPATIBLE`（7001）
低於 (接收方最高版本 - 1) 的主版本	必須返回 `VERSION_INCOMPATIBLE`（7001）
同主版本，更低次版本	正常處理（向後相容）
同主版本，更高次版本	應處理（忽略不識別的可選欄位）

10.2.1 次版本號容錯（§1.7.3 的操作性落地）

接收到主版本號相同但次版本號更高的訊框時，實作必須：

處理已知欄位；
應忽略未知的可選欄位；
不得因未知可選欄位而拒絕整個訊框；
不得拋出錯誤。

10.3 版本不相容處理（操作機制）

10.3.1 接收方處理

接收方收到協定版本號高於自身支援版本（且超出相容範圍）的 LogicalFrame 時必須：

不處理 該訊框；
向傳送方傳送 VERSION_INCOMPATIBLE 錯誤（7001）；
在錯誤通知的 details 欄位中包含自身支援的最高版本號：

{
  errorCode: 7001,
  errorMessage: "Protocol version higher than supported",
  details: {
    supportedMaxVersion: { major: 1, minor: 0 }
  }
}

錯誤碼 7001 的語義以第 9 章錯誤碼表與 schema 為準，本章不另立定義。

10.3.2 傳送方處理

傳送方收到 VERSION_INCOMPATIBLE 錯誤後可選擇：

降級到對端支援的版本 重新傳送該訊框（應優先選擇，前提是雙方存在共同 MAJOR；跨 MAJOR 不降級，見 §1.7.3）；
通知上層應用 版本不相容，不得自動持續重試。

實作不得在收到版本不相容錯誤後立即關閉會話，應給予降級機會。

10.3.3 會話內版本一致性與協商時序

DTP 會話建立時，雙方必須協商一致的協定版本（協商規則見 §1.7.3）。會話期間：

協商後整個會話必須使用統一的版本；
不得在會話進行中切換協定版本。

版本協商應遵循以下時序，具體承載方式（CAP 擴充、首個 Request_Frame/Response_Frame 等）可由實作選擇，但必須在第一個資料訊框傳送前完成：

DTP_A                              DTP_B
  |                                   |
  |-- Hello (supported_versions) --->|
  |                                   |
  |<-- Hello_Ack (chosen_version) ---|
  |                                   |
  |    [雙方使用 chosen_version]       |

10.4 協定演進與治理

本節給出 §1.7 治理規則的操作流程。其中涉及的 git tag 格式、文件狀態列舉、編輯版次定義，必須以 §1.7 為規則錨點，本節不重定義。

10.4.1 目錄與狀態約定（與 Faying Protocol 一致）

文件狀態是 front matter 標記，不得編碼進路徑（見 §1.7.1）。
specification/ 下必須僅保留唯一一個可變工作區 draft/（滾動更新）。
除 draft/ 外的所有目錄必須以發布日期命名（如 2025-10-25/），代表一個凍結的已發布版次；「非草案即已發布」。
某發布版次當前是 Final 還是 Deprecated / Obsolete，僅由其檔案的 status 欄位決定，不得依據目錄名判斷。
禁止建立以狀態命名的目錄（如 final/）——否則版次被棄用時需搬移目錄、破壞連結。
WHEN 發生狀態流轉，必須僅修改 front matter 的 status，且目錄不得移動。

10.4.2 草案與正式版本

草案：文件存放於 docs/{lang}/specification/draft/，schema 存放於 schema/draft/；草案版本號可使用 { major: 0, minor: N }。Draft 期間無相容性承諾（見 §1.7.5），且不得用於正式環境。
正式版本：必須經過完整評審與公開討論，擁有不可變的版本快照；文件存放於 docs/{lang}/specification/{YYYY-MM-DD}/，schema 存放於 schema/{YYYY-MM-DD}/。第一個正式版本為 2025-10-25，對應協定版本 dtp/1.0。
版本快照不可變性：正式版本一經發布必須保持不可變；純文字勘誤按 §1.7.4 以新的發布日期目錄承載，既有目錄凍結，不得原地改寫已發布快照的規範內容或 schema。

10.4.3 定稿標準動作（Draft → Final）

WHEN 執行定稿，Doc Governance Process 必須依次完成以下動作：

透過 git mv 將 draft/ 下全部檔案遷移至發布日期目錄（檔名不變），並清空 draft/；
逐檔將 status 由 Draft 改為 Final；
將 date 固化為正式發布日期，將 editors 鎖定為定稿署名名單，並保持 version 不變；
在 README front matter 中寫入 replaces 歷史鏈（指向草案目錄及其定稿提交短雜湊）；
打 tag dtp-v<MAJOR.MINOR>-final，該 tag 必須同時涵蓋正文 + 測試向量 + schema；
涉及多語言 / 多檔案時，必須在同一次提交中一併遷移，不得單邊發布。

10.4.4 棄用與移除

實作應透過以下流程棄用功能：

標記為棄用：在 MINOR 版本中將功能標記為 deprecated，但必須繼續支援；
過渡期：至少經過一個完整的 MAJOR 版本週期；
移除：在下一個 MAJOR 版本中移除。

實作不得在 MINOR 版本中移除已棄用的功能。

10.5 實作宣告

DTP 實作必須在文件中宣告：

支援的最高協定版本；
支援的所有前序主版本；
是否支援未來相容（處理更高次版本的訊框）；
實作定義的擴充（如有）。

例如：

DTP 實作 X 版本宣告：

支援的最高協定版本：1.0

相容前序版本：無（首個正式版本）

未來相容：支援，會忽略未知的可選欄位

加密演算法：AES-256-GCM、ChaCha20-Poly1305

傳輸介面卡：BLE、WebSocket、TCP

第 10 章 版本管理