版本控管、穩定性、棄用與支援政策

概覽

每個 NextPDF 文件頁面都在其 front matter 中攜帶生命週期欄位： stability、since、deprecated_since、replaced_by、version_lifecycle 與 eol_date。那些欄位已編碼了一份支援合約。本頁把該合約陳述於一處，讓一個正式環境團隊能讀取任何頁面的中繼資料，並對固定某個版本做風險評估。

NextPDF 的發行編號遵循 Semantic Versioning 2.0.0，並以 Conventional Commits 1.0.0 產生變更日誌。服務提供者介面（NextPDF\Contracts 與 NextPDF\Event 中的公開合約）受同一套規則治理；關於每合約的 @stability 標籤機制，請見 SPI 穩定性規則。本頁是 SPI 規則所特化之較廣泛的政策。

NextPDF 的語意化版本控管

一個發行版本是 MAJOR.MINOR.PATCH。改變的位置告訴你你的程式碼中有什麼可以改變：

增量	它的意義	什麼可能破壞
主版本（`3.x` → `4.0.0`）	允許破壞性變更。	一個 `stable` 合約可能改變簽章或被移除；一個在前一個主版本中標記的已棄用符號可能被刪除；預設行為可能改變。
次版本（`6.0` → `6.1.0`）	向後相容的新增。	對一個 `stable` 合約而言沒有任何東西。一個已發佈的穩定介面不會新增必要方法；增長來自新的合約/介面、具體類別上的選用方法，以及帶預設值的新建構子/設定選項。一個 `experimental` 合約可能在此改變，且會先有棄用通知。
修補版本（`4.0.0` → `3.2.1`）	向後相容的錯誤修正。	沒有任何刻意的東西。行為朝有記載的合約收斂。

stable 介面的實務規則：像 ^3.2 這樣的 Composer 限制會收到其主版本線內的每個次版本與修補發行，且不帶破壞性變更。破壞性變更只落在主版本邊界上。

{
    "require": {
        "nextpdf/core": "^3.2"
    }
}

當你依賴一個 experimental 合約時，請更緊密地固定（例如 ~3.2.0），因為一個 experimental 合約可能在一個次版本發行中改變。

穩定性標籤

一個頁面的 stability 欄位，與一個合約的原始 @stability 標籤，取自同一套詞彙。標籤陳述相容性承諾的強度。

標籤	它保證什麼	它在哪裡改變
`stable`	可用於正式環境。可安全依賴。在一個次版本或修補發行中沒有破壞性變更。一個穩定介面（例如 `NextPDF\Contracts` SPI）在一個次版本或修補中不會新增必要方法——向後相容的增長以一個新合約、一個具體類別上的選用方法，或經由帶預設值的建構子/設定選項到來。	僅限主版本發行。
`beta`	功能完整且可用，但介面尚未凍結。為了固定，請把它當作 `experimental` 對待：包裝或緊密固定。	可能在一個次版本發行中改變，且會先有棄用通知。
`experimental`	可用，但明確尚未凍結。NextPDF 可能在公開合約仍在移動時就出貨一個經測試的引擎實作。	可能在一個次版本發行中改變，且會先有棄用通知。
`deprecated`	已排定移除。頁面或合約陳述其替代品，以及它在哪個主版本中被移除。	在下一個主版本中移除；絕不在次版本或修補中。

串流合約 NextPDF\Contracts\CursorInterface 與 NextPDF\Contracts\StreamingWriterInterface 是 experimental 介面的真實範例：NextPDF 出貨最終、經測試的實作，但公開合約仍可能在一個次版本發行中改變。在你於正式環境中依賴這樣一個合約之前，請緊密固定它或把它包裝在你自己的轉接器之後。

棄用生命週期

棄用是一條已定義的四步路徑。它總是指名替代品，而移除總是延後到一個主版本邊界：

標記。 擁有者在一個合約上設定 @stability deprecated（或在一個頁面上設定 deprecated_since），並記下替代品與移除的主版本。在一個頁面上，deprecated_since 是引入棄用的版本，而 replaced_by 是規範的後繼路徑。
通知。 棄用在標記它之發行的變更日誌中宣布。
重疊。 被棄用的介面與其替代品至少共存一個次版本發行，因此你可以在不需要一次性切換日的情況下遷移。
移除。 介面在所述的主版本發行中被移除。移除絕不發生在一個次版本或修補發行中。

文件中有一個已走完整個生命週期的頁面層級範例：舊式的 /docs/cookbook/php/sign-pades/ 範例先被標記為 deprecated_since: "3.0.0"，並以 replaced_by: /docs/cookbook/php/sign-pades-b-b/ 指向其後繼者，在重疊窗口期間與後繼者共存，其後便已退役——舊網址如今會以一個永久重新導向回應，指向該後繼範例，因此那些針對這個已棄用（deprecated）頁面所寫下的連結，在移除之後仍能持續運作。

一旦某個介面被標記為 deprecated，請盡快規劃遷移。由於替代品總是被陳述，且兩者至少重疊一個次版本，你可以在移除的主版本到來之前移動。

版本生命週期與安全支援

version_lifecycle 欄位分類一個有記載的版本線如何維護。其值為：

`version_lifecycle`	意義	收到
`active`	處於積極開發中的目前線。	功能、修正與安全修正。
`lts`	一條長期支援線。	在其支援期間內的修正與安全修正。
`maintenance`	已過積極開發，仍維護中。	安全修正與嚴重錯誤修正。
`frozen`	不再規劃任何功能變更。	僅在適用時的安全修正。
`eol`	生命週期終止。	沒有任何東西。需要升級。

當一條線到達生命週期終止時，其 eol_date 記錄該日期（ISO 8601， YYYY-MM-DD）。一個帶有 version_lifecycle: eol 與一個過去 eol_date 的頁面，是一個從該線遷移走的訊號：它不再收到修正，包含安全修正。

這是一份政策陳述，不是一個日曆承諾。這些欄位告訴你一條線所處之支援的類別；至於攜帶某個給定修正的具體版本，請查閱變更日誌與發行說明。安全修正會 backport 到其生命週期仍包含它們的線（active、lts 與 maintenance），而非那些標記為不適用的 frozen 或 eol 的線。

PHP 版本支援窗口

NextPDF Core 需要 PHP >=8.4 <9.0。那個窗口宣告於引擎的 composer.json 中，是唯一的真實來源；premium 套件（nextpdf/pro、nextpdf/enterprise）需要相同的範圍。

下界（>=8.4）是最低執行環境。提高它是一項破壞性變更，且只落在一個主版本邊界上。
上界（<9.0）在下一個 PHP 主版本經驗證之前排除它。對一個新 PHP 主版本的支援是在一個 NextPDF 發行中加入的，而非被假定的。

文件頁面也攜帶一個 compatibility 清單，列出一個範例經驗證所對應的 PHP 次版本。一個頁面在範例可攜之處可能列出較舊的次版本（例如 ["8.1", "8.2", "8.3", "8.4"]），而引擎的硬性安裝底線仍是 >=8.4。有疑慮時，composer.json 限制勝過一個頁面的 compatibility 提示。

如何閱讀一個頁面的生命週期 front matter

在你以一個頁面為基礎建置之前，用這六個欄位評估它：

欄位	型別	如何閱讀它
`stability`	`stable` \| `beta` \| `experimental` \| `deprecated`	頁面所記載介面的相容性承諾。
`since`	SemVer（例如 `"3.1.0"`）	引入該有記載介面的版本。你的安裝至少必須是這個版本。
`deprecated_since`	SemVer 或空	若已設定，該介面已被棄用；其值是棄用它的版本。空代表未棄用。
`replaced_by`	站台路徑或空	當已棄用時，要遷移到的規範後繼頁面。
`version_lifecycle`	`active` \| `lts` \| `maintenance` \| `frozen` \| `eol`	有記載線的維護類別。
`eol_date`	ISO 日期或空	當 `version_lifecycle` 為 `eol` 時，生命週期終止日期。否則為空。

一個示範閱讀：一個帶有 stability: stable、since: "3.0.0"、 deprecated_since: "" 與 version_lifecycle: active 的頁面，記載一個自 3.0.0 起即存在、未被棄用、且位於積極維護線上的可用於正式環境的介面。你可以在一個 ^ 主版本限制下依賴它。一個帶有 stability: deprecated 與一個非空 replaced_by 的頁面是一個遷移訊號：閱讀後繼頁面，並在下一個主版本之前規劃移動。

規範性

本政策就版本編號符合 Semantic Versioning 2.0.0，並就變更日誌產生符合 Conventional Commits 1.0.0。PHP 支援窗口是引擎 composer.json 中宣告的 >=8.4 <9.0 限制。本頁本身不作任何規範性標準主張；它記載生命週期 front-matter 欄位已編碼的支援合約。

另請參閱

SPI 穩定性規則——每合約的 @stability 標籤與四個向後相容性承諾類別（介面、列舉、凍結值物件、實驗性）。
CSS 支援矩陣——HTML 與 CSS 算繪管線經真相稽核的每模組支援狀態。
參考索引——API、設定與相容性參考材料的進入點。