バージョニング、安定性、非推奨、サポートポリシー

概要

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 は最終的なテスト済みの実装を出荷しますが、公開契約はまだマイナーリリースで変わりうります。本番でそれに依存する前に、そのような契約を厳しく固定するか、自分のアダプターの背後にラップしてください。

非推奨ライフサイクル

非推奨は、定義された 4 ステップのパスです。それは常に置き換えを名指しし、削除は常にメジャーの境界へ延期されます。

印を付ける（Mark）。 オーナーが契約に @stability deprecated を（またはページに deprecated_since を）設定し、置き換えと削除メジャーを記録します。ページでは、 deprecated_since が非推奨を導入したバージョンで、replaced_by が正規の後継パスです。
通知（Notice）。 非推奨は、それに印を付けるリリースの変更履歴で告知されます。
重複（Overlap）。 非推奨になった面とその置き換えが、少なくとも 1 つのマイナーリリースの間共存するため、フラグデーなしで移行できます。
削除（Remove）。 面は、述べられたメジャーリリースで削除されます。削除がマイナーやパッチリリースで起こることは決してありません。

ライフサイクル全体を完走したページレベルの例もあります。レガシーの /docs/cookbook/php/sign-pades/ レシピは deprecated_since: "3.0.0" と replaced_by: /docs/cookbook/php/sign-pades-b-b/ で印を付けられ、重複ウィンドウの間はその後継と共存し、その後に退役しました――古い URL はいまや後継レシピへの恒久的なリダイレクトで応答するため、deprecated になったページに対して書かれたリンクは、削除後も動作し続けます。

面が deprecated と印を付けられたら、すぐに移行を計画してください。置き換えは常に述べられ、両者が少なくとも 1 つのマイナーの間重複するため、削除するメジャーが到着する前に移動できます。

バージョンライフサイクルとセキュリティサポート

version_lifecycle フィールドは、文書化されたバージョンラインがどう保守されるかを分類します。値は次のとおりです。

`version_lifecycle`	意味	受け取るもの
`active`	アクティブに開発中の現在のライン。	機能、修正、セキュリティ修正。
`lts`	長期サポートライン。	そのサポートウィンドウの間の修正とセキュリティ修正。
`maintenance`	アクティブな開発を過ぎたが、まだ保守されている。	セキュリティ修正と深刻なバグの修正。
`frozen`	これ以上の機能変更は計画されていない。	該当する場合、セキュリティ修正のみ。
`eol`	寿命終了（End of life）。	何もなし。アップグレードが必要。

ラインが寿命終了に達すると、その eol_date が日付（ISO 8601、YYYY-MM-DD）を記録します。version_lifecycle: eol と過去の eol_date を持つページは、そのラインから移行するシグナルです。それはもはや、セキュリティ修正を含む修正を受け取りません。

これはポリシーの記述であり、カレンダー上の約束ではありません。フィールドは、ラインがどの クラス のサポートにあるかを教えます。特定の修正を運ぶ具体的なバージョンについては、変更履歴とリリースノートを参照してください。セキュリティ修正は、ライフサイクルに依然それらを含むライン（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 のリリースで追加されます。

ドキュメントページは、レシピが検証された PHP マイナーバージョンの compatibility リストも持ちます。ページは、レシピが移植可能な古いマイナー（例えば ["8.1", "8.2", "8.3", "8.4"]）を列挙しうる一方で、エンジンのハードなインストールの下限は >=8.4 のままです。疑わしいときは、ページの compatibility ヒントよりも composer.json 制約が優先します。

ページのライフサイクル front matter の読み方

これら 6 つのフィールドを使って、それに基づいて構築する前に任意のページを評価します。

フィールド	型	読み方
`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 フィールドがすでにエンコードしているサポート契約を文書化します。