Versionierung, Stabilität, Deprecation und Support-Policy

Auf einen Blick

Jede NextPDF-Dokumentationsseite trägt Lebenszyklusfelder in ihrem Front Matter: stability, since, deprecated_since, replaced_by, version_lifecycle und eol_date. Diese Felder codieren bereits einen Support-Vertrag. Diese Seite formuliert diesen Vertrag an einer Stelle, sodass ein Produktionsteam die Metadaten jeder Seite lesen und das Pinnen einer Version risikobewerten kann.

NextPDF folgt Semantic Versioning 2.0.0 für seine Release-Nummern und Conventional Commits 1.0.0 für die Changelog-Generierung. Die Service-Provider-Schnittstelle (die öffentlichen Verträge in NextPDF\Contracts und NextPDF\Event) unterliegt denselben Regeln; siehe SPI-Stabilitätsregeln für die Mechanik des @stability-Tags pro Vertrag. Diese Seite ist die umfassendere Policy, die die SPI-Regeln spezialisieren.

Semantische Versionierung für NextPDF

Eine Release-Version lautet MAJOR.MINOR.PATCH. Die Position, die sich ändert, sagt Ihnen, was sich in Ihrem Code ändern kann:

Inkrement	Was es bedeutet	Was brechen darf
Major (3.x → 4.0.0)	Breaking Changes sind erlaubt.	Ein stable-Vertrag darf seine Signatur ändern oder entfernt werden; ein im vorherigen Major als veraltet markiertes Symbol darf gelöscht werden; das Standardverhalten darf sich ändern.
Minor (6.0 → 6.1.0)	Abwärtskompatible Ergänzungen.	Nichts für einen stable-Vertrag. Eine veröffentlichte stabile Schnittstelle gewinnt keine neuen Pflichtmethoden; Wachstum kommt aus neuen Verträgen/Schnittstellen, optionalen Methoden an konkreten Klassen und neuen Konstruktor-/Config-Optionen mit Standardwerten. Ein experimental-Vertrag darf sich hier ändern, mit einem vorherigen Deprecation-Hinweis.
Patch (4.0.0 → 3.2.1)	Abwärtskompatible Bugfixes.	Nichts Beabsichtigtes. Das Verhalten konvergiert in Richtung des dokumentierten Vertrags.

Die praktische Regel für eine stable-Oberfläche: Ein Composer-Constraint wie ^3.2 erhält jedes Minor- und Patch-Release seiner Major-Linie ohne Breaking Change. Breaking Changes landen nur an einer Major-Grenze.

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

Pinnen Sie enger (zum Beispiel ~3.2.0), wenn Sie von einem experimental-Vertrag abhängen, da sich ein experimental-Vertrag in einem Minor-Release ändern darf.

Stabilitätslabels

Das stability-Feld einer Seite und der @stability-Tag im Quellcode eines Vertrags schöpfen aus demselben Vokabular. Das Label gibt die Stärke des Kompatibilitätsversprechens an.

Label	Was es garantiert	Wo es sich ändert
stable	Produktionsreif. Sicher, davon abzuhängen. Keine Breaking Change in einem Minor- oder Patch-Release. Eine stabile Schnittstelle (wie die NextPDF\Contracts-SPI) gewinnt in einem Minor oder Patch keine neuen Pflichtmethoden – abwärtskompatibles Wachstum kommt über einen neuen Vertrag, als optionale Methode an einer konkreten Klasse oder über Konstruktor-/Config-Optionen mit Standardwerten.	Nur Major-Release.
beta	Funktionsvollständig und nutzbar, aber die Oberfläche ist noch nicht eingefroren. Behandeln Sie es zum Pinnen wie experimental: kapseln oder eng pinnen.	Darf sich in einem Minor-Release ändern, mit einem vorherigen Deprecation-Hinweis.
experimental	Nutzbar, aber ausdrücklich nicht eingefroren. NextPDF darf eine getestete Engine-Implementierung ausliefern, während sich der öffentliche Vertrag noch bewegt.	Darf sich in einem Minor-Release ändern, mit einem vorherigen Deprecation-Hinweis.
deprecated	Zur Entfernung vorgesehen. Die Seite oder der Vertrag nennt den Ersatz und den Major, in dem es entfernt wird.	Im nächsten Major entfernt; niemals in einem Minor oder Patch.

Die Streaming-Verträge NextPDF\Contracts\CursorInterface und NextPDF\Contracts\StreamingWriterInterface sind reale Beispiele für experimental-Oberflächen: NextPDF liefert finale, getestete Implementierungen aus, aber der öffentliche Vertrag darf sich noch in einem Minor-Release ändern. Pinnen Sie einen solchen Vertrag eng oder kapseln Sie ihn hinter Ihrem eigenen Adapter, bevor Sie in der Produktion von ihm abhängen.

Deprecation-Lebenszyklus

Deprecation ist ein definierter, vierstufiger Weg. Sie nennt immer den Ersatz, und die Entfernung wird stets auf eine Major-Grenze verschoben:

1. Markieren. Der Eigner setzt @stability deprecated auf einen Vertrag (oder deprecated_since auf einer Seite) und erfasst den Ersatz sowie den Entfernungs-Major. Auf einer Seite ist deprecated_since die Version, die die Deprecation eingeführt hat, und replaced_by ist der kanonische Nachfolgerpfad.
2. Hinweis. Die Deprecation wird im Changelog für das Release angekündigt, das sie markiert.
3. Überlappung. Die veraltete Oberfläche und ihr Ersatz koexistieren für mindestens ein Minor-Release, sodass Sie ohne Stichtag migrieren können.
4. Entfernen. Die Oberfläche wird im genannten Major-Release entfernt. Die Entfernung geschieht niemals in einem Minor- oder Patch-Release.

Ein Beispiel auf Seitenebene, das den gesamten Weg bereits durchlaufen hat: Das veraltete Recipe /docs/cookbook/php/sign-pades/ wurde mit deprecated_since: "3.0.0" und replaced_by: /docs/cookbook/php/sign-pades-b-b/ als veraltet markiert, koexistierte während des Überlappungsfensters mit seinem Nachfolger und wurde inzwischen entfernt – die alte URL antwortet nun mit einem permanenten Redirect auf das Nachfolger-Recipe, sodass Links, die gegen die deprecated-Seite geschrieben wurden, auch nach der Entfernung weiter funktionieren.

Planen Sie eine Migration, sobald eine Oberfläche als deprecated markiert ist. Weil der Ersatz stets genannt wird und die beiden für mindestens ein Minor überlappen, können Sie umziehen, bevor der entfernende Major eintrifft.

Versions-Lebenszyklus und Sicherheits-Support

Das version_lifecycle-Feld klassifiziert, wie eine dokumentierte Versionslinie gepflegt wird. Die Werte sind:

version_lifecycle	Bedeutung	Erhält
active	Die aktuelle Linie unter aktiver Entwicklung.	Features, Fixes und Sicherheitsfixes.
lts	Eine Long-Term-Support-Linie.	Fixes und Sicherheitsfixes für ihr Support-Fenster.
maintenance	Über die aktive Entwicklung hinaus, weiterhin gepflegt.	Sicherheitsfixes und Fixes für schwere Fehler.
frozen	Keine weitere funktionale Änderung geplant.	Nur Sicherheitsfixes, wo zutreffend.
eol	End of Life.	Nichts. Ein Upgrade ist erforderlich.

Wenn eine Linie das End of Life erreicht, erfasst ihr eol_date das Datum (ISO 8601, YYYY-MM-DD). Eine Seite mit version_lifecycle: eol und einem vergangenen eol_date ist ein Signal, von dieser Linie wegzumigrieren: Sie erhält keine Fixes mehr, einschließlich Sicherheitsfixes.

Dies ist eine Policy-Aussage, kein Kalenderversprechen. Die Felder sagen Ihnen die Klasse des Supports, in der eine Linie steht; konsultieren Sie den Changelog und die Release Notes für die konkrete Version, die einen gegebenen Fix trägt. Sicherheitsfixes werden in die Linien zurückportiert, deren Lebenszyklus sie noch einschließt (active, lts und maintenance), nicht in Linien, die als frozen-ohne-Anwendbarkeit oder eol markiert sind.

PHP-Versions-Support-Fenster

NextPDF Core erfordert PHP >=8.4 <9.0. Dieses Fenster ist in der composer.json der Engine deklariert und ist die einzige Quelle der Wahrheit; die Premium-Pakete (nextpdf/pro, nextpdf/enterprise) erfordern denselben Bereich.

• Die untere Grenze (>=8.4) ist die minimale Laufzeit. Sie anzuheben ist eine Breaking Change und landet nur an einer Major-Grenze.
• Die obere Grenze (<9.0) schließt den nächsten PHP-Major aus, bis er validiert wurde. Die Unterstützung für einen neuen PHP-Major wird in einem NextPDF-Release hinzugefügt, nicht angenommen.

Dokumentationsseiten tragen außerdem eine compatibility-Liste der PHP-Minor-Versionen, gegen die ein Recipe verifiziert ist. Eine Seite darf ältere Minors listen (zum Beispiel ["8.1", "8.2", "8.3", "8.4"]), wo das Recipe portabel ist, während die harte Installationsuntergrenze der Engine >=8.4 bleibt. Im Zweifelsfall hat der composer.json-Constraint Vorrang vor dem compatibility-Hinweis einer Seite.

So lesen Sie das Lebenszyklus-Front-Matter einer Seite

Verwenden Sie diese sechs Felder, um jede Seite zu bewerten, bevor Sie darauf aufbauen:

Feld	Typ	Wie es zu lesen ist
stability	stable | beta | experimental | deprecated	Das Kompatibilitätsversprechen für die Oberfläche, die die Seite dokumentiert.
since	SemVer (z. B. "3.1.0")	Die Version, die die dokumentierte Oberfläche eingeführt hat. Ihre Installation muss mindestens diese Version haben.
deprecated_since	SemVer oder leer	Falls gesetzt, ist die Oberfläche veraltet; der Wert ist die Version, die sie als veraltet markiert hat. Leer bedeutet nicht veraltet.
replaced_by	Site-Pfad oder leer	Wenn veraltet, die kanonische Nachfolgerseite, zu der migriert werden soll.
version_lifecycle	active | lts | maintenance | frozen | eol	Die Wartungsklasse der dokumentierten Linie.
eol_date	ISO-Datum oder leer	Wenn version_lifecycle eol ist, das End-of-Life-Datum. Andernfalls leer.

Ein durchgespieltes Lesen: Eine Seite mit stability: stable, since: "3.0.0", deprecated_since: "" und version_lifecycle: active dokumentiert eine produktionsreife Oberfläche, die seit 3.0.0 existiert, nicht veraltet ist und auf der aktiv gepflegten Linie sitzt. Sie können unter einem ^-Major-Constraint von ihr abhängen. Eine Seite mit stability: deprecated und einem nicht-leeren replaced_by ist ein Migrationssignal: Lesen Sie die Nachfolgerseite und planen Sie den Umzug vor dem nächsten Major.

Konformität

Diese Policy entspricht Semantic Versioning 2.0.0 für die Versionsnummerierung und Conventional Commits 1.0.0 für die Changelog-Generierung. Das PHP-Support-Fenster ist der in der Engine-composer.json deklarierte >=8.4 <9.0-Constraint. Diese Seite erhebt keinen eigenen normativen Standardanspruch; sie dokumentiert den Support-Vertrag, den die Lebenszyklus-Front-Matter-Felder bereits codieren.

Siehe auch

• SPI-Stabilitätsregeln – der @stability-Tag pro Vertrag und die vier Abwärtskompatibilitäts-Versprechensklassen (Schnittstelle, Enum, eingefrorenes Wertobjekt, experimentell).
• CSS-Support-Matrix – der wahrheitsgeprüfte Per-Modul-Support-Zustand für die HTML- und CSS-Rendering-Pipeline.
• Referenz-Index – der Einstiegspunkt für API-, Konfigurations- und Kompatibilitäts-Referenzmaterial.