版本管理、稳定性、弃用与支持策略

概览

每个 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/；它在重叠窗口内与其后继共存，此后已被退役 —— 如今旧 URL 以一个永久重定向作答，指向那份后继示例，因此针对这个 deprecated 页面写下的链接在移除之后仍能继续工作。

一旦一个接口被标记 deprecated，就尽快规划一次迁移。因为替代品总是被陈述，且两者至少重叠一个次版本，你可以在那个移除主版本到来之前就行动。

版本生命周期与安全支持

version_lifecycle 字段对一个有文档的版本线如何维护进行分类。各取值是：

`version_lifecycle`	含义	收到
`active`	当前处于活跃开发中的线。	功能、修复和安全修复。
`lts`	一条长期支持线。	在其支持窗口内的修复和安全修复。
`maintenance`	已过活跃开发，仍在维护。	安全修复和严重缺陷修复。
`frozen`	不再计划任何功能性变更。	仅安全修复，在适用之处。
`eol`	生命终止。	没有任何东西。必须升级。

当一条线到达生命终止时，它的 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 里，是唯一的真理来源；高级版包（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、配置和兼容性参考资料的入口。