Версионирование, стабильность, объявление устаревшим и политика поддержки

Кратко

Каждая страница документации 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) управляется теми же правилами; см. Правила стабильности SPI для механики тега @stability на каждый контракт. Эта страница — более широкая политика, которую специализируют правила SPI.

Семантическое версионирование для NextPDF

Версия релиза — это MAJOR.MINOR.PATCH. Позиция, которая меняется, говорит вам, что может измениться в вашем коде:

Инкремент	Что это означает	Что может сломаться
Major (3.x → 4.0.0)	Разрешены ломающие изменения.	Контракт stable может изменить сигнатуру или быть удалён; устаревший символ, помеченный в предыдущем major, может быть удалён; поведение по умолчанию может измениться.
Minor (6.0 → 6.1.0)	Обратно совместимые добавления.	Ничего для контракта stable. Опубликованный стабильный интерфейс не получает новых обязательных методов; рост идёт через новые контракты/интерфейсы, необязательные методы на конкретных классах и новые опции конструктора/конфигурации со значениями по умолчанию. Контракт experimental может измениться здесь, сначала с уведомлением об устаревании.
Patch (4.0.0 → 3.2.1)	Обратно совместимые исправления ошибок.	Ничего намеренного. Поведение сходится к документированному контракту.

Практическое правило для поверхности stable: ограничение Composer, такое как ^3.2, получает каждый минорный и патч-релиз своей major-линии без ломающего изменения. Ломающие изменения приходят только на границе major.

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

Закрепляйте более жёстко (например ~3.2.0), когда вы зависите от контракта experimental, потому что контракт experimental может измениться в минорном релизе.

Метки стабильности

Поле stability страницы и исходный тег @stability контракта черпают из одного и того же словаря. Метка формулирует силу обещания совместимости.

Метка	Что она гарантирует	Где она меняется
stable	Готов к продакшену. Безопасно полагаться. Никакого ломающего изменения в минорном или патч-релизе. Стабильный интерфейс (такой как SPI NextPDF\Contracts) не получает новых обязательных методов в минорном или патче — обратно совместимый рост приходит на новом контракте, как необязательный метод на конкретном классе или через опции конструктора/конфигурации со значениями по умолчанию.	Только на major-релизе.
beta	Завершён по возможностям и пригоден к использованию, но поверхность ещё не заморожена. Относитесь к нему как к experimental при закреплении: оборачивайте или закрепляйте жёстко.	Может измениться в минорном релизе, сначала с уведомлением об устаревании.
experimental	Пригоден к использованию, но явно не заморожен. NextPDF может поставлять протестированную реализацию движка, пока публичный контракт ещё движется.	Может измениться в минорном релизе, сначала с уведомлением об устаревании.
deprecated	Запланирован к удалению. Страница или контракт указывают свою замену и major, в котором он удаляется.	Удаляется в следующем major; никогда в минорном или патче.

Потоковые контракты NextPDF\Contracts\CursorInterface и NextPDF\Contracts\StreamingWriterInterface — реальные примеры поверхностей experimental: NextPDF поставляет финальные, протестированные реализации, но публичный контракт ещё может измениться в минорном релизе. Закрепляйте жёстко или оборачивайте такой контракт за собственным адаптером, прежде чем зависеть от него в продакшене.

Жизненный цикл устаревания

Устаревание — это определённый путь из четырёх шагов. Он всегда называет замену, а удаление всегда отложено до границы major:

1. Пометка. Владелец устанавливает @stability deprecated на контракте (или deprecated_since на странице) и записывает замену и major удаления. На странице deprecated_since — это версия, которая ввела устаревание, а replaced_by — канонический путь-преемник.
2. Уведомление. Устаревание объявляется в списке изменений релиза, который его помечает.
3. Перекрытие. Устаревшая поверхность и её замена сосуществуют по меньшей мере один минорный релиз, чтобы вы могли мигрировать без «дня X».
4. Удаление. Поверхность удаляется в заявленном major-релизе. Удаление никогда не происходит в минорном или патч-релизе.

Пример уровня страницы, прошедший весь жизненный цикл целиком: устаревший рецепт /docs/cookbook/php/sign-pades/ был помечен deprecated_since: "3.0.0" вместе с replaced_by: /docs/cookbook/php/sign-pades-b-b/, сосуществовал со своим преемником в течение окна перекрытия и с тех пор выведен из эксплуатации — старый URL теперь отвечает постоянным перенаправлением на рецепт-преемник, так что ссылки, ведущие на страницу с меткой deprecated, продолжают работать даже после её удаления.

Планируйте миграцию сразу, как только поверхность помечена deprecated. Поскольку замена всегда указана, а две перекрываются по меньшей мере один минор, вы можете переехать до прихода удаляющего major.

Жизненный цикл версии и поддержка безопасности

Поле 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) — это минимальная среда выполнения. Её повышение — ломающее изменение, и оно приходит только на границе major.
• Верхняя граница (<9.0) исключает следующий major PHP, пока он не валидирован. Поддержка нового major 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, не устарела и находится на активно сопровождаемой линии. Вы можете зависеть от неё под ^-major-ограничением. Страница с stability: deprecated и непустым replaced_by — это сигнал к миграции: прочитайте страницу-преемника и спланируйте переезд до следующего major.

Соответствие стандартам

Эта политика соответствует Semantic Versioning 2.0.0 для нумерации версий и Conventional Commits 1.0.0 для генерации списка изменений. Окно поддержки PHP — это ограничение >=8.4 <9.0, объявленное в composer.json движка. Эта страница не делает собственного нормативного заявления о стандартах; она документирует контракт поддержки, который поля жизненного цикла во front matter уже кодируют.

См. также

• Правила стабильности SPI — тег @stability на каждый контракт и четыре класса обещания обратной совместимости (интерфейс, перечисление, замороженный объект-значение, экспериментальный).
• Матрица поддержки CSS — проверенное по истине состояние поддержки на каждый модуль для конвейера отрисовки HTML и CSS.
• Индекс справочника — точка входа для справочного материала по API, конфигурации и совместимости.