Versionering, stabiliteit, deprecation en supportbeleid

In één oogopslag

Elke NextPDF-documentatiepagina draagt lifecycle-velden in zijn front matter: stability, since, deprecated_since, replaced_by, version_lifecycle en eol_date. Die velden coderen al een supportcontract. Deze pagina stelt dat contract op één plek vast zodat een productieteam de metadata van elke pagina kan lezen en het vastpinnen van een versie kan risico-inschatten.

NextPDF volgt Semantic Versioning 2.0.0 voor zijn releasenummers en Conventional Commits 1.0.0 voor changelog-generatie. De service provider interface (de publieke contracten in NextPDF\Contracts en NextPDF\Event) wordt geregeerd door dezelfde regels; zie SPI-stabiliteitsregels voor de per-contract @stability-tag-mechanica. Deze pagina is het bredere beleid dat de SPI-regels specialiseren.

Semantische versionering voor NextPDF

Een releaseversie is MAJOR.MINOR.PATCH. De positie die verandert vertelt je wat er in je code kan veranderen:

Verhoging	Wat het betekent	Wat kan breken
Major (3.x → 4.0.0)	Breaking changes zijn toegestaan.	Een stable-contract kan van signatuur veranderen of worden verwijderd; een gedeprecieerd symbool dat in de vorige major is gemarkeerd, kan worden verwijderd; standaardgedrag kan veranderen.
Minor (6.0 → 6.1.0)	Backward-compatibele toevoegingen.	Niets voor een stable-contract. Een gepubliceerde stabiele interface krijgt geen nieuwe verplichte methoden; groei komt van nieuwe contracten/interfaces, optionele methoden op concrete klassen, en nieuwe constructor-/config-opties met standaardwaarden. Een experimental-contract kan hier veranderen, eerst met een deprecation-melding.
Patch (4.0.0 → 3.2.1)	Backward-compatibele bugfixes.	Niets opzettelijk. Gedrag convergeert naar het gedocumenteerde contract.

De praktische regel voor een stable-oppervlak: een Composer-constraint zoals ^3.2 ontvangt elke minor- en patch-release van zijn major-lijn zonder breaking change. Breaking changes landen alleen op een major-grens.

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

Pin strakker (bijvoorbeeld ~3.2.0) wanneer je afhankelijk bent van een experimental-contract, omdat een experimental-contract in een minor-release kan veranderen.

Stabiliteitslabels

Het stability-veld van een pagina, en de bron-@stability-tag van een contract, putten uit hetzelfde vocabulaire. Het label stelt de sterkte van de compatibiliteitsbelofte vast.

Label	Wat het garandeert	Waar het verandert
stable	Productieklaar. Veilig om op te bouwen. Geen breaking change in een minor- of patch-release. Een stabiele interface (zoals de NextPDF\Contracts-SPI) krijgt geen nieuwe verplichte methoden in een minor of patch — backward-compatibele groei arriveert op een nieuw contract, als een optionele methode op een concrete klasse, of via constructor-/config-opties met standaardwaarden.	Alleen major-release.
beta	Functiecompleet en bruikbaar, maar het oppervlak is nog niet bevroren. Behandel het als experimental voor het vastpinnen: wrap of pin strak.	Kan in een minor-release veranderen, eerst met een deprecation-melding.
experimental	Bruikbaar, maar expliciet niet bevroren. NextPDF kan een geteste engine-implementatie verschepen terwijl het publieke contract nog beweegt.	Kan in een minor-release veranderen, eerst met een deprecation-melding.
deprecated	Gepland voor verwijdering. De pagina of het contract vermeldt zijn vervanging en de major waarin het wordt verwijderd.	Verwijderd in de volgende major; nooit in een minor of patch.

De streaming-contracten NextPDF\Contracts\CursorInterface en NextPDF\Contracts\StreamingWriterInterface zijn echte voorbeelden van experimental-oppervlakken: NextPDF verscheept definitieve, geteste implementaties, maar het publieke contract kan nog in een minor-release veranderen. Pin strak of wrap zo’n contract achter je eigen adapter voordat je er in productie op vertrouwt.

Deprecation-lifecycle

Deprecation is een gedefinieerd, vierstaps pad. Het benoemt altijd de vervanging, en verwijdering wordt altijd uitgesteld tot een major-grens:

1. Markeren. De eigenaar zet @stability deprecated op een contract (of deprecated_since op een pagina) en legt de vervanging en de verwijderings-major vast. Op een pagina is deprecated_since de versie die de deprecation introduceerde en replaced_by het canonieke opvolgerpad.
2. Melding. De deprecation wordt aangekondigd in de changelog voor de release die het markeert.
3. Overlap. Het gedeprecieerde oppervlak en zijn vervanging bestaan ten minste één minor-release naast elkaar, zodat je kunt migreren zonder een flag day.
4. Verwijderen. Het oppervlak wordt verwijderd in de aangegeven major-release. Verwijdering gebeurt nooit in een minor- of patch-release.

Een voorbeeld op paginaniveau dat de hele lifecycle heeft doorlopen: het legacy-recipe /docs/cookbook/php/sign-pades/ werd gemarkeerd met deprecated_since: "3.0.0" en replaced_by: /docs/cookbook/php/sign-pades-b-b/, bestond gedurende het overlapvenster naast zijn opvolger en is sindsdien verwijderd — de oude URL antwoordt nu met een permanente redirect naar het opvolgerrecipe, zodat links die naar de gedeprecieerde pagina zijn geschreven ook na verwijdering blijven werken.

Plan een migratie zodra een oppervlak als deprecated is gemarkeerd. Omdat de vervanging altijd wordt vermeld en de twee ten minste één minor overlappen, kun je verhuizen voordat de verwijderende major arriveert.

Versie-lifecycle en beveiligingssupport

Het version_lifecycle-veld classificeert hoe een gedocumenteerde versielijn wordt onderhouden. De waarden zijn:

version_lifecycle	Betekenis	Ontvangt
active	De huidige lijn onder actieve ontwikkeling.	Features, fixes en beveiligingsfixes.
lts	Een long-term-support-lijn.	Fixes en beveiligingsfixes voor zijn supportvenster.
maintenance	Voorbij actieve ontwikkeling, nog onderhouden.	Beveiligingsfixes en ernstige-bugfixes.
frozen	Geen verdere functionele wijziging gepland.	Alleen beveiligingsfixes, waar van toepassing.
eol	End of life.	Niets. Upgrade is vereist.

Wanneer een lijn end of life bereikt, legt zijn eol_date de datum vast (ISO 8601, YYYY-MM-DD). Een pagina met version_lifecycle: eol en een verleden eol_date is een signaal om van die lijn af te migreren: hij ontvangt geen fixes meer, inclusief beveiligingsfixes.

Dit is een beleidsverklaring, geen kalenderbelofte. De velden vertellen je de klasse van support waarin een lijn zit; raadpleeg de changelog en release notes voor de concrete versie die een bepaalde fix draagt. Beveiligingsfixes worden gebackport naar de lijnen waarvan de lifecycle ze nog omvat (active, lts en maintenance), niet naar lijnen gemarkeerd als frozen-zonder-toepasselijkheid of eol.

PHP-versie-supportvenster

NextPDF Core vereist PHP >=8.4 <9.0. Dat venster is gedeclareerd in de composer.json van de engine en is de enige bron van waarheid; de premiumpakketten (nextpdf/pro, nextpdf/enterprise) vereisen hetzelfde bereik.

• De ondergrens (>=8.4) is de minimale runtime. Het verhogen is een breaking change en landt alleen op een major-grens.
• De bovengrens (<9.0) sluit de volgende PHP-major uit totdat die is gevalideerd. Support voor een nieuwe PHP-major wordt in een NextPDF-release toegevoegd, niet aangenomen.

Documentatiepagina’s dragen ook een compatibility-lijst van de PHP-minor-versies waartegen een recipe is geverifieerd. Een pagina kan oudere minors vermelden (bijvoorbeeld ["8.1", "8.2", "8.3", "8.4"]) waar het recipe portabel is, terwijl de harde installatievloer van de engine >=8.4 blijft. Bij twijfel wint de composer.json-constraint boven de compatibility-hint van een pagina.

Hoe je de lifecycle-front-matter van een pagina leest

Gebruik deze zes velden om elke pagina te beoordelen voordat je erop bouwt:

Veld	Type	Hoe je het leest
stability	stable | beta | experimental | deprecated	De compatibiliteitsbelofte voor het oppervlak dat de pagina documenteert.
since	SemVer (bijv. "3.1.0")	De versie die het gedocumenteerde oppervlak introduceerde. Je installatie moet ten minste deze versie zijn.
deprecated_since	SemVer of leeg	Indien gezet, is het oppervlak gedeprecieerd; de waarde is de versie die het deprecieerde. Leeg betekent niet gedeprecieerd.
replaced_by	Site-pad of leeg	Bij deprecation de canonieke opvolgerpagina om naartoe te migreren.
version_lifecycle	active | lts | maintenance | frozen | eol	De onderhoudsklasse van de gedocumenteerde lijn.
eol_date	ISO-datum of leeg	Wanneer version_lifecycle eol is, de end-of-life-datum. Anders leeg.

Een uitgewerkte lezing: een pagina met stability: stable, since: "3.0.0", deprecated_since: "" en version_lifecycle: active documenteert een productieklaar oppervlak dat sinds 3.0.0 bestaat, niet gedeprecieerd is, en op de actief onderhouden lijn zit. Je kunt erop vertrouwen onder een ^-major-constraint. Een pagina met stability: deprecated en een niet-lege replaced_by is een migratiesignaal: lees de opvolgerpagina en plan de verhuizing vóór de volgende major.

Conformiteit

Dit beleid conformeert aan Semantic Versioning 2.0.0 voor versienummering en aan Conventional Commits 1.0.0 voor changelog-generatie. Het PHP-supportvenster is de >=8.4 <9.0-constraint die in de engine-composer.json is gedeclareerd. Deze pagina doet geen eigen normatieve standaardenclaim; het documenteert het supportcontract dat de lifecycle-front-matter-velden al coderen.

Zie ook

• SPI-stabiliteitsregels — de per-contract @stability-tag en de vier backward-compatibiliteits-belofteklassen (interface, enum, bevroren waardeobject, experimental).
• CSS-ondersteuningsmatrix — de waarheid-geaudite per-module-ondersteuningsstaat voor de HTML- en CSS-renderpijplijn.
• Referentie-index — het toegangspunt voor API-, configuratie- en compatibiliteitsreferentiemateriaal.