Politica di versionamento, stabilità, deprecazione e supporto

In sintesi

Ogni pagina della documentazione di NextPDF porta campi di ciclo di vita nel proprio front matter: stability, since, deprecated_since, replaced_by, version_lifecycle ed eol_date. Quei campi codificano già un contratto di supporto. Questa pagina enuncia tale contratto in un unico luogo, così che un team di produzione possa leggere i metadati di qualsiasi pagina e valutare il rischio di fissare una versione.

NextPDF segue il Semantic Versioning 2.0.0 per i numeri di release e i Conventional Commits 1.0.0 per la generazione del changelog. La service provider interface (i contratti pubblici in NextPDF\Contracts e NextPDF\Event) è governata dalle stesse regole; si vedano le regole di stabilità SPI per i meccanismi del tag @stability per contratto. Questa pagina è la politica più ampia che le regole SPI specializzano.

Semantic versioning per NextPDF

Una versione di release è MAJOR.MINOR.PATCH. La posizione che cambia indica cosa può cambiare nel proprio codice:

Incremento	Cosa significa	Cosa può rompersi
Major (3.x → 4.0.0)	Le modifiche incompatibili sono consentite.	Un contratto stable può cambiare firma o essere rimosso; un simbolo deprecato contrassegnato nel major precedente può essere eliminato; il comportamento predefinito può cambiare.
Minor (6.0 → 6.1.0)	Aggiunte retrocompatibili.	Nulla per un contratto stable. Un’interfaccia stabile pubblicata non acquisisce alcun nuovo metodo richiesto; la crescita proviene da nuovi contratti/interfacce, metodi facoltativi su classi concrete e nuove opzioni di costruttore/configurazione con valori predefiniti. Un contratto experimental può cambiare qui, con un avviso di deprecazione prima.
Patch (4.0.0 → 3.2.1)	Correzioni di bug retrocompatibili.	Nulla di intenzionale. Il comportamento converge verso il contratto documentato.

La regola pratica per una superficie stable: un vincolo Composer come ^3.2 riceve ogni release minor e patch della propria linea major senza una modifica incompatibile. Le modifiche incompatibili atterrano soltanto su un confine major.

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

Fissare più strettamente (ad esempio ~3.2.0) quando si dipende da un contratto experimental, perché un contratto experimental può cambiare in una release minor.

Etichette di stabilità

Il campo stability di una pagina, e il tag sorgente @stability di un contratto, attingono allo stesso vocabolario. L’etichetta enuncia la forza della promessa di compatibilità.

Etichetta	Cosa garantisce	Dove cambia
stable	Pronto per la produzione. Sicuro su cui dipendere. Nessuna modifica incompatibile in una release minor o patch. Un’interfaccia stabile (come la SPI NextPDF\Contracts) non acquisisce nuovi metodi richiesti in una minor o patch — la crescita retrocompatibile arriva su un nuovo contratto, come metodo facoltativo su una classe concreta, o tramite opzioni di costruttore/configurazione con valori predefiniti.	Solo release major.
beta	Completa nelle funzionalità e utilizzabile, ma la superficie non è ancora congelata. Trattarla come experimental per il pinning: incapsularla o fissarla strettamente.	Può cambiare in una release minor, con un avviso di deprecazione prima.
experimental	Utilizzabile, ma esplicitamente non congelata. NextPDF può distribuire un’implementazione del motore testata mentre il contratto pubblico è ancora in movimento.	Può cambiare in una release minor, con un avviso di deprecazione prima.
deprecated	Programmata per la rimozione. La pagina o il contratto enuncia la propria sostituzione e il major in cui viene rimossa.	Rimossa nel major successivo; mai in una minor o patch.

I contratti di streaming NextPDF\Contracts\CursorInterface e NextPDF\Contracts\StreamingWriterInterface sono esempi reali di superfici experimental: NextPDF distribuisce implementazioni finali e testate, ma il contratto pubblico può ancora cambiare in una release minor. Fissare strettamente o incapsulare un contratto simile dietro un proprio adattatore prima di farne affidamento in produzione.

Ciclo di vita della deprecazione

La deprecazione è un percorso definito in quattro passaggi. Nomina sempre la sostituzione, e la rimozione è sempre rinviata a un confine major:

1. Contrassegnare. Il proprietario imposta @stability deprecated su un contratto (o deprecated_since su una pagina) e registra la sostituzione e il major di rimozione. Su una pagina, deprecated_since è la versione che ha introdotto la deprecazione e replaced_by è il percorso del successore canonico.
2. Avvisare. La deprecazione viene annunciata nel changelog della release che la contrassegna.
3. Sovrapporre. La superficie deprecata e la sua sostituzione coesistono per almeno una release minor, così da poter migrare senza un giorno di transizione improvvisa.
4. Rimuovere. La superficie viene rimossa nella release major indicata. La rimozione non avviene mai in una release minor o patch.

Un esempio a livello di pagina che ha percorso l’intero arco: la ricetta legacy /docs/cookbook/php/sign-pades/ è stata contrassegnata con deprecated_since: "3.0.0" e replaced_by: /docs/cookbook/php/sign-pades-b-b/, ha coesistito con il proprio successore per l’intera finestra di sovrapposizione ed è stata poi ritirata: il vecchio URL risponde ora con un reindirizzamento permanente alla ricetta successore, così che i collegamenti scritti verso la pagina deprecated continuino a funzionare anche dopo la rimozione.

Pianificare una migrazione non appena una superficie viene contrassegnata come deprecated. Poiché la sostituzione è sempre enunciata e le due si sovrappongono per almeno una minor, è possibile spostarsi prima che arrivi il major di rimozione.

Ciclo di vita della versione e supporto alla sicurezza

Il campo version_lifecycle classifica come una linea di versione documentata viene mantenuta. I valori sono:

version_lifecycle	Significato	Riceve
active	La linea corrente sotto sviluppo attivo.	Funzionalità, correzioni e correzioni di sicurezza.
lts	Una linea a supporto a lungo termine.	Correzioni e correzioni di sicurezza per la sua finestra di supporto.
maintenance	Oltre lo sviluppo attivo, ancora mantenuta.	Correzioni di sicurezza e correzioni di bug gravi.
frozen	Nessun ulteriore cambiamento funzionale pianificato.	Solo correzioni di sicurezza, dove applicabili.
eol	Fine vita.	Nulla. L’aggiornamento è richiesto.

Quando una linea raggiunge la fine vita, il suo eol_date registra la data (ISO 8601, YYYY-MM-DD). Una pagina con version_lifecycle: eol e un eol_date passato è un segnale per migrare via da quella linea: non riceve più correzioni, incluse le correzioni di sicurezza.

Questa è una dichiarazione di politica, non una promessa di calendario. I campi indicano la classe di supporto in cui si trova una linea; consultare il changelog e le note di release per la versione concreta che porta una determinata correzione. Le correzioni di sicurezza vengono retroportate alle linee il cui ciclo di vita le include ancora (active, lts e maintenance), non alle linee contrassegnate come frozen-senza-applicabilità o eol.

Finestra di supporto delle versioni di PHP

NextPDF Core richiede PHP >=8.4 <9.0. Quella finestra è dichiarata nel composer.json del motore ed è l’unica fonte di verità; i pacchetti premium (nextpdf/pro, nextpdf/enterprise) richiedono lo stesso intervallo.

• Il limite inferiore (>=8.4) è il runtime minimo. Innalzarlo è una modifica incompatibile e atterra soltanto su un confine major.
• Il limite superiore (<9.0) esclude il prossimo major di PHP finché non è stato convalidato. Il supporto a un nuovo major di PHP viene aggiunto in una release di NextPDF, non presupposto.

Anche le pagine della documentazione portano un elenco compatibility delle versioni minor di PHP rispetto alle quali una ricetta è verificata. Una pagina può elencare minor più vecchie (ad esempio ["8.1", "8.2", "8.3", "8.4"]) dove la ricetta è portabile, mentre il pavimento di installazione vincolante del motore resta >=8.4. In caso di dubbio, il vincolo del composer.json prevale su un suggerimento compatibility di una pagina.

Come leggere il front matter di ciclo di vita di una pagina

Usare questi sei campi per valutare qualsiasi pagina prima di costruirvi sopra:

Campo	Tipo	Come leggerlo
stability	stable | beta | experimental | deprecated	La promessa di compatibilità per la superficie che la pagina documenta.
since	SemVer (ad esempio "3.1.0")	La versione che ha introdotto la superficie documentata. La propria installazione deve essere almeno a questa versione.
deprecated_since	SemVer o vuoto	Se impostato, la superficie è deprecata; il valore è la versione che l’ha deprecata. Vuoto significa non deprecata.
replaced_by	Percorso del sito o vuoto	Quando deprecata, la pagina del successore canonico verso cui migrare.
version_lifecycle	active | lts | maintenance | frozen | eol	La classe di manutenzione della linea documentata.
eol_date	Data ISO o vuoto	Quando version_lifecycle è eol, la data di fine vita. Vuoto altrimenti.

Una lettura applicata: una pagina con stability: stable, since: "3.0.0", deprecated_since: "" e version_lifecycle: active documenta una superficie pronta per la produzione, esistente dalla 3.0.0, non deprecata e collocata sulla linea attivamente mantenuta. È possibile dipenderne sotto un vincolo major ^. Una pagina con stability: deprecated e un replaced_by non vuoto è un segnale di migrazione: leggere la pagina del successore e pianificare lo spostamento prima del major successivo.

Conformità

Questa politica è conforme al Semantic Versioning 2.0.0 per la numerazione delle versioni e ai Conventional Commits 1.0.0 per la generazione del changelog. La finestra di supporto di PHP è il vincolo >=8.4 <9.0 dichiarato nel composer.json del motore. Questa pagina non avanza alcuna affermazione normativa di conformità a standard di per sé; documenta il contratto di supporto che i campi di ciclo di vita del front matter già codificano.

Vedere anche

• Regole di stabilità SPI — il tag @stability per contratto e le quattro classi di promessa di retrocompatibilità (interfaccia, enum, value-object congelato, sperimentale).
• Matrice di supporto CSS — lo stato di supporto per modulo, verificato sulla verità, per la pipeline di rendering di HTML e CSS.
• Indice del riferimento — il punto di ingresso per il materiale di riferimento di API, configurazione e compatibilità.