Politique de versionnage, de stabilité, de dépréciation et de support

En un coup d’œil

Chaque page de documentation NextPDF porte des champs de cycle de vie dans son front matter : stability, since, deprecated_since, replaced_by, version_lifecycle et eol_date. Ces champs encodent déjà un contrat de support. Cette page énonce ce contrat en un seul endroit pour qu’une équipe de production puisse lire les métadonnées de n’importe quelle page et évaluer le risque d’épingler une version.

NextPDF suit Semantic Versioning 2.0.0 pour ses numéros de version et Conventional Commits 1.0.0 pour la génération du changelog. L’interface du fournisseur de service (les contrats publics dans NextPDF\Contracts et NextPDF\Event) est régie par les mêmes règles ; voir Règles de stabilité du SPI pour la mécanique de l’étiquette @stability par contrat. Cette page est la politique plus large que les règles du SPI spécialisent.

Versionnage sémantique pour NextPDF

Une version de release est MAJOR.MINOR.PATCH. La position qui change t’indique ce qui peut changer dans ton code :

Incrément	Ce que cela signifie	Ce qui peut casser
Majeur (3.x → 4.0.0)	Les changements cassants sont permis.	Un contrat stable peut changer de signature ou être retiré ; un symbole déprécié marqué dans le majeur précédent peut être supprimé ; le comportement par défaut peut changer.
Mineur (6.0 → 6.1.0)	Ajouts rétrocompatibles.	Rien pour un contrat stable. Une interface stable publiée ne gagne aucune nouvelle méthode requise ; la croissance vient de nouveaux contrats/interfaces, de méthodes optionnelles sur des classes concrètes, et de nouvelles options de constructeur/config avec valeurs par défaut. Un contrat experimental peut changer ici, avec un avis de dépréciation d’abord.
Correctif (4.0.0 → 3.2.1)	Corrections de bugs rétrocompatibles.	Rien d’intentionnel. Le comportement converge vers le contrat documenté.

La règle pratique pour une surface stable : une contrainte Composer telle que ^3.2 reçoit chaque release mineure et corrective de sa version majeure sans changement cassant. Les changements cassants n’atterrissent que sur une frontière majeure.

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

Épingle plus étroitement (par exemple ~3.2.0) quand tu dépends d’un contrat experimental, parce qu’un contrat experimental peut changer dans une release mineure.

Étiquettes de stabilité

Le champ stability d’une page, et l’étiquette source @stability d’un contrat, puisent dans le même vocabulaire. L’étiquette énonce la force de la promesse de compatibilité.

Étiquette	Ce qu’elle garantit	Où elle change
stable	Prête pour la production. Sûre comme dépendance. Aucun changement cassant dans une release mineure ou corrective. Une interface stable (telle que le SPI NextPDF\Contracts) ne gagne aucune nouvelle méthode requise dans un mineur ou un correctif — la croissance rétrocompatible arrive sur un nouveau contrat, comme méthode optionnelle sur une classe concrète, ou via des options de constructeur/config avec valeurs par défaut.	Release majeure uniquement.
beta	Complète en fonctionnalités et utilisable, mais la surface n’est pas encore figée. Traite-la comme experimental pour l’épinglage : encapsule ou épingle étroitement.	Peut changer dans une release mineure, avec un avis de dépréciation d’abord.
experimental	Utilisable, mais explicitement non figée. NextPDF peut livrer une implémentation de moteur testée pendant que le contrat public bouge encore.	Peut changer dans une release mineure, avec un avis de dépréciation d’abord.
deprecated	Programmée pour retrait. La page ou le contrat énonce son remplacement et le majeur dans lequel il est retiré.	Retirée dans le prochain majeur ; jamais dans un mineur ni un correctif.

Les contrats de flux NextPDF\Contracts\CursorInterface et NextPDF\Contracts\StreamingWriterInterface sont de vrais exemples de surfaces experimental : NextPDF livre des implémentations finales et testées, mais le contrat public peut encore changer dans une release mineure. Épingle étroitement ou encapsule un tel contrat derrière ton propre adaptateur avant d’en dépendre en production.

Cycle de vie de la dépréciation

La dépréciation est un chemin défini en quatre étapes. Elle nomme toujours le remplacement, et le retrait est toujours différé à une frontière majeure :

1. Marquer. Le propriétaire définit @stability deprecated sur un contrat (ou deprecated_since sur une page) et enregistre le remplacement et le majeur de retrait. Sur une page, deprecated_since est la version qui a introduit la dépréciation et replaced_by est le chemin successeur canonique.
2. Aviser. La dépréciation est annoncée dans le changelog de la release qui la marque.
3. Chevaucher. La surface dépréciée et son remplacement coexistent pendant au moins une release mineure, pour que tu puisses migrer sans jour de bascule.
4. Retirer. La surface est retirée dans la release majeure annoncée. Le retrait ne se produit jamais dans une release mineure ni corrective.

Un exemple au niveau page qui a parcouru tout le cycle : la recette héritée /docs/cookbook/php/sign-pades/ a été marquée deprecated_since: "3.0.0" avec replaced_by: /docs/cookbook/php/sign-pades-b-b/, a coexisté avec son successeur pendant la fenêtre de chevauchement, puis a depuis été retirée — l’ancienne URL répond désormais par une redirection permanente vers la recette successeur, de sorte que les liens écrits vers la page deprecated continuent de fonctionner après le retrait.

Planifie une migration dès qu’une surface est marquée deprecated. Parce que le remplacement est toujours énoncé et que les deux se chevauchent pendant au moins un mineur, tu peux bouger avant l’arrivée du majeur de retrait.

Cycle de vie de version et support de sécurité

Le champ version_lifecycle classe la façon dont une ligne de version documentée est maintenue. Les valeurs sont :

version_lifecycle	Signification	Reçoit
active	La ligne actuelle en développement actif.	Fonctionnalités, correctifs et correctifs de sécurité.
lts	Une ligne à support à long terme.	Correctifs et correctifs de sécurité pour sa fenêtre de support.
maintenance	Au-delà du développement actif, encore maintenue.	Correctifs de sécurité et correctifs de bugs sérieux.
frozen	Aucun changement fonctionnel ultérieur prévu.	Correctifs de sécurité uniquement, le cas échéant.
eol	Fin de vie.	Rien. Une mise à niveau est requise.

Quand une ligne atteint la fin de vie, son eol_date enregistre la date (ISO 8601, YYYY-MM-DD). Une page avec version_lifecycle: eol et un eol_date passé est un signal de migrer hors de cette ligne : elle ne reçoit plus de correctifs, y compris de sécurité.

C’est un énoncé de politique, pas une promesse de calendrier. Les champs t’indiquent la classe de support dans laquelle se trouve une ligne ; consulte le changelog et les notes de release pour la version concrète qui porte un correctif donné. Les correctifs de sécurité sont rétroportés vers les lignes dont le cycle de vie les inclut encore (active, lts et maintenance), pas vers les lignes marquées frozen-sans-applicabilité ou eol.

Fenêtre de support des versions PHP

NextPDF Core exige PHP >=8.4 <9.0. Cette fenêtre est déclarée dans le composer.json du moteur et est la source unique de vérité ; les paquets premium (nextpdf/pro, nextpdf/enterprise) exigent la même plage.

• La borne inférieure (>=8.4) est le runtime minimum. La relever est un changement cassant et n’atterrit que sur une frontière majeure.
• La borne supérieure (<9.0) exclut le prochain majeur PHP tant qu’il n’a pas été validé. La prise en charge d’un nouveau majeur PHP est ajoutée dans une release NextPDF, pas présumée.

Les pages de documentation portent aussi une liste compatibility des versions mineures PHP contre lesquelles une recette est vérifiée. Une page peut lister des mineures plus anciennes (par exemple ["8.1", "8.2", "8.3", "8.4"]) là où la recette est portable, tandis que le plancher d’installation strict du moteur reste >=8.4. En cas de doute, la contrainte du composer.json l’emporte sur l’indice compatibility d’une page.

Comment lire le front matter de cycle de vie d’une page

Utilise ces six champs pour évaluer toute page avant de construire dessus :

Champ	Type	Comment le lire
stability	stable | beta | experimental | deprecated	La promesse de compatibilité de la surface que la page documente.
since	SemVer (ex. "3.1.0")	La version qui a introduit la surface documentée. Ton installation doit être au moins à cette version.
deprecated_since	SemVer ou vide	Si défini, la surface est dépréciée ; la valeur est la version qui l’a dépréciée. Vide signifie non déprécié.
replaced_by	Chemin du site ou vide	Une fois dépréciée, la page successeur canonique vers laquelle migrer.
version_lifecycle	active | lts | maintenance | frozen | eol	La classe de maintenance de la ligne documentée.
eol_date	Date ISO ou vide	Quand version_lifecycle est eol, la date de fin de vie. Vide sinon.

Une lecture travaillée : une page avec stability: stable, since: "3.0.0", deprecated_since: "" et version_lifecycle: active documente une surface prête pour la production qui existe depuis 3.0.0, n’est pas dépréciée, et se trouve sur la ligne activement maintenue. Tu peux en dépendre sous une contrainte majeure ^. Une page avec stability: deprecated et un replaced_by non vide est un signal de migration : lis la page successeur et planifie le déplacement avant le prochain majeur.

Conformité

Cette politique est conforme à Semantic Versioning 2.0.0 pour la numérotation des versions et à Conventional Commits 1.0.0 pour la génération du changelog. La fenêtre de support PHP est la contrainte >=8.4 <9.0 déclarée dans le composer.json du moteur. Cette page ne fait aucune revendication normative de standard qui lui soit propre ; elle documente le contrat de support que les champs de front matter de cycle de vie encodent déjà.

Voir aussi

• Règles de stabilité du SPI — l’étiquette @stability par contrat et les quatre classes de promesse de rétrocompatibilité (interface, énumération, objet valeur figé, expérimental).
• Matrice de prise en charge CSS — l’état de prise en charge par module, audité pour véracité, du pipeline de rendu HTML et CSS.
• Index de référence — le point d’entrée du matériel de référence d’API, de configuration et de compatibilité.