Política de versionado, estabilidad, obsolescencia y soporte

En resumen

Cada página de documentación de NextPDF lleva campos de ciclo de vida en su front matter: stability, since, deprecated_since, replaced_by, version_lifecycle y eol_date. Esos campos ya codifican un contrato de soporte. Esta página enuncia ese contrato en un solo lugar para que un equipo de producción pueda leer los metadatos de cualquier página y evaluar el riesgo de fijar una versión.

NextPDF sigue Semantic Versioning 2.0.0 para sus números de versión y Conventional Commits 1.0.0 para la generación del registro de cambios. La interfaz del proveedor de servicios (los contratos públicos en NextPDF\Contracts y NextPDF\Event) se rige por las mismas reglas; consulta Reglas de estabilidad de la SPI para la mecánica de la etiqueta @stability por contrato. Esta página es la política más amplia que las reglas de la SPI especializan.

Versionado semántico para NextPDF

Una versión de lanzamiento es MAJOR.MINOR.PATCH. La posición que cambia te dice qué puede cambiar en tu código:

Incremento	Qué significa	Qué puede romperse
Mayor (3.x → 4.0.0)	Se permiten cambios incompatibles.	Un contrato stable puede cambiar de firma o eliminarse; un símbolo obsoleto marcado en la versión mayor anterior puede borrarse; el comportamiento predeterminado puede cambiar.
Menor (6.0 → 6.1.0)	Adiciones compatibles con versiones anteriores.	Nada para un contrato stable. Una interfaz estable publicada no gana ningún método requerido nuevo; el crecimiento procede de nuevos contratos/interfaces, métodos opcionales en clases concretas y nuevas opciones de constructor/configuración con valores predeterminados. Un contrato experimental puede cambiar aquí, con un aviso de obsolescencia primero.
Parche (4.0.0 → 3.2.1)	Correcciones de errores compatibles con versiones anteriores.	Nada intencionado. El comportamiento converge hacia el contrato documentado.

La regla práctica para una superficie stable: una restricción de Composer como ^3.2 recibe cada versión menor y de parche de su línea mayor sin un cambio incompatible. Los cambios incompatibles aterrizan solo en un límite de versión mayor.

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

Fija con más rigor (por ejemplo ~3.2.0) cuando dependas de un contrato experimental, porque un contrato experimental puede cambiar en una versión menor.

Etiquetas de estabilidad

El campo stability de una página, y la etiqueta @stability de origen de un contrato, parten del mismo vocabulario. La etiqueta enuncia la fuerza de la promesa de compatibilidad.

Etiqueta	Qué garantiza	Dónde cambia
stable	Listo para producción. Seguro para depender de él. Sin cambio incompatible en una versión menor o de parche. Una interfaz estable (como la SPI NextPDF\Contracts) no gana ningún método requerido nuevo en una versión menor o de parche: el crecimiento compatible con versiones anteriores llega en un contrato nuevo, como un método opcional en una clase concreta, o mediante opciones de constructor/configuración con valores predeterminados.	Solo en una versión mayor.
beta	Funcionalmente completo y utilizable, pero la superficie aún no está congelada. Trátalo como experimental para fijar: envuélvelo o fíjalo con rigor.	Puede cambiar en una versión menor, con un aviso de obsolescencia primero.
experimental	Utilizable, pero explícitamente no congelado. NextPDF puede entregar una implementación del motor probada mientras el contrato público aún se mueve.	Puede cambiar en una versión menor, con un aviso de obsolescencia primero.
deprecated	Programado para eliminación. La página o el contrato enuncian su reemplazo y la versión mayor en la que se elimina.	Eliminado en la siguiente versión mayor; nunca en una menor o de parche.

Los contratos de transmisión NextPDF\Contracts\CursorInterface y NextPDF\Contracts\StreamingWriterInterface son ejemplos reales de superficies experimental: NextPDF entrega implementaciones finales y probadas, pero el contrato público aún puede cambiar en una versión menor. Fija con rigor o envuelve tal contrato tras tu propio adaptador antes de depender de él en producción.

Ciclo de vida de la obsolescencia

La obsolescencia es una vía definida de cuatro pasos. Siempre nombra el reemplazo, y la eliminación siempre se difiere a un límite de versión mayor:

1. Marcar. El responsable establece @stability deprecated en un contrato (o deprecated_since en una página) y registra el reemplazo y la versión mayor de eliminación. En una página, deprecated_since es la versión que introdujo la obsolescencia y replaced_by es la ruta canónica sucesora.
2. Avisar. La obsolescencia se anuncia en el registro de cambios de la versión que la marca.
3. Solapar. La superficie obsoleta y su reemplazo coexisten durante al menos una versión menor, para que puedas migrar sin un día de corte.
4. Eliminar. La superficie se elimina en la versión mayor enunciada. La eliminación nunca ocurre en una versión menor o de parche.

Un ejemplo a nivel de página que ha completado todo el recorrido: la receta antigua /docs/cookbook/php/sign-pades/ se marcó con deprecated_since: "3.0.0" y replaced_by: /docs/cookbook/php/sign-pades-b-b/, coexistió con su sucesora durante la ventana de solapamiento y desde entonces se ha retirado: la antigua URL responde ahora con una redirección permanente hacia la receta sucesora, de modo que los enlaces escritos contra la página obsoleta siguen funcionando tras su eliminación.

Planifica una migración en cuanto una superficie se marque como deprecated. Como el reemplazo siempre se enuncia y los dos se solapan durante al menos una versión menor, puedes moverte antes de que llegue la versión mayor que la elimina.

Ciclo de vida de versión y soporte de seguridad

El campo version_lifecycle clasifica cómo se mantiene una línea de versión documentada. Los valores son:

version_lifecycle	Significado	Recibe
active	La línea actual bajo desarrollo activo.	Funciones, correcciones y correcciones de seguridad.
lts	Una línea de soporte a largo plazo.	Correcciones y correcciones de seguridad durante su ventana de soporte.
maintenance	Superado el desarrollo activo, aún mantenida.	Correcciones de seguridad y correcciones de errores graves.
frozen	Sin más cambios funcionales planeados.	Solo correcciones de seguridad, cuando aplica.
eol	Fin de vida.	Nada. Se requiere actualizar.

Cuando una línea alcanza el fin de vida, su eol_date registra la fecha (ISO 8601, YYYY-MM-DD). Una página con version_lifecycle: eol y un eol_date pasado es una señal para migrar fuera de esa línea: ya no recibe correcciones, incluidas las de seguridad.

Esta es una declaración de política, no una promesa de calendario. Los campos te dicen la clase de soporte en la que está una línea; consulta el registro de cambios y las notas de la versión para la versión concreta que lleva una corrección dada. Las correcciones de seguridad se retroportan a las líneas cuyo ciclo de vida aún las incluye (active, lts y maintenance), no a las líneas marcadas como frozen-sin-aplicabilidad o eol.

Ventana de soporte de versiones de PHP

NextPDF Core requiere PHP >=8.4 <9.0. Esa ventana se declara en el composer.json del motor y es la única fuente de verdad; los paquetes premium (nextpdf/pro, nextpdf/enterprise) requieren el mismo rango.

• El límite inferior (>=8.4) es el entorno de ejecución mínimo. Subirlo es un cambio incompatible y aterriza solo en un límite de versión mayor.
• El límite superior (<9.0) excluye la siguiente versión mayor de PHP hasta que se haya validado. La compatibilidad con una nueva versión mayor de PHP se añade en una versión de NextPDF, no se asume.

Las páginas de documentación también llevan una lista compatibility de las versiones menores de PHP frente a las que se ha verificado una receta. Una página puede listar versiones menores más antiguas (por ejemplo ["8.1", "8.2", "8.3", "8.4"]) donde la receta es portable, mientras que el suelo de instalación estricto del motor sigue siendo >=8.4. En caso de duda, la restricción del composer.json prevalece sobre la pista compatibility de una página.

Cómo leer el front matter de ciclo de vida de una página

Usa estos seis campos para evaluar cualquier página antes de construir sobre ella:

Campo	Tipo	Cómo leerlo
stability	stable | beta | experimental | deprecated	La promesa de compatibilidad de la superficie que documenta la página.
since	SemVer (p. ej. "3.1.0")	La versión que introdujo la superficie documentada. Tu instalación debe ser al menos esta versión.
deprecated_since	SemVer o vacío	Si está establecido, la superficie está obsoleta; el valor es la versión que la marcó obsoleta. Vacío significa no obsoleta.
replaced_by	Ruta del sitio o vacío	Cuando está obsoleta, la página sucesora canónica a la que migrar.
version_lifecycle	active | lts | maintenance | frozen | eol	La clase de mantenimiento de la línea documentada.
eol_date	Fecha ISO o vacío	Cuando version_lifecycle es eol, la fecha de fin de vida. Vacío en caso contrario.

Una lectura trabajada: una página con stability: stable, since: "3.0.0", deprecated_since: "" y version_lifecycle: active documenta una superficie lista para producción que ha existido desde la 3.0.0, no está obsoleta y se asienta en la línea mantenida activamente. Puedes depender de ella bajo una restricción mayor ^. Una página con stability: deprecated y un replaced_by no vacío es una señal de migración: lee la página sucesora y planifica el cambio antes de la siguiente versión mayor.

Conformidad

Esta política se ajusta a Semantic Versioning 2.0.0 para la numeración de versiones y a Conventional Commits 1.0.0 para la generación del registro de cambios. La ventana de soporte de PHP es la restricción >=8.4 <9.0 declarada en el composer.json del motor. Esta página no hace ninguna afirmación normativa de estándares por sí misma; documenta el contrato de soporte que los campos de ciclo de vida del front matter ya codifican.

Véase también

• Reglas de estabilidad de la SPI — la etiqueta @stability por contrato y las cuatro clases de promesa de compatibilidad con versiones anteriores (interfaz, enumeración, objeto de valor congelado, experimental).
• Matriz de compatibilidad de CSS — el estado de compatibilidad por módulo, auditado por veracidad, de la canalización de representación de HTML y CSS.
• Índice de referencia — el punto de entrada para el material de referencia de API, configuración y compatibilidad.