Ejecutar el compilador del backport en un flujo de publicación

Herramienta de compilación: NO es una dependencia en tiempo de ejecución. Esta página describe cómo operar el flujo de publicación que produce el backport. El flujo se ejecuta en CI; nunca se ejecuta en una aplicación consumidora.

De un vistazo

La ruta de producción utiliza dos flujos de trabajo. 0-ci.yml controla todos los cambios en cualquiera de las dos ramas permanentes. build.yml produce y publica la distribución, y lo activa una publicación de origen. Ambos se verifican en .github/workflows/.

La barrera de CI

0-ci.yml se ejecuta con cada push y pull request hacia PHP74 y PHP81. Consta de tres trabajos, que se ejecutan en orden:

1. PHPStan (herramientas de compilación) — composer analyse, nivel 10 aplicado a rector/rules y scripts.
2. PHPUnit (reglas de Rector) — composer test, los conjuntos de fixtures de las tres reglas personalizadas.
3. Compilación en seco — composer build:dry, dependiente de los dos primeros trabajos.

Los eventos de confianza se ejecutan en runners de PHP autoalojados. Los pull requests desde bifurcaciones y Dependabot se ejecutan en runners alojados por GitHub con PHP 8.5 aprovisionado. Verificado en 0-ci.yml (la expresión runs-on y el paso condicional setup-php). El modelo de dos ramas permite controlar de forma independiente, en el pull request de cada rama, un cambio que afecte a ambos destinos.

El flujo de publicación

build.yml es la compilación de producción. Se activa mediante un evento repository_dispatch de tipo source-release, o manualmente mediante workflow_dispatch con una etiqueta como entrada. La etiqueta de versión rige todo el proceso. Un número de versión tiene el formato MAJOR.MINOR.PATCH para una API pública declarada (Semantic Versioning 2.0.0 §2).

Vía de PHP 8.1

1. build-php81 — extraer las herramientas de compilación, aprovisionar PHP 8.5, instalar las dependencias de compilación, clonar los repositorios de origen en la etiqueta de publicación, ejecutar scripts/build.php, cambiar el runner a PHP 8.1, comprobar la sintaxis de output/src en PHP 8.1 y, a continuación, instalar el paquete generado con --no-dev. La salida se sube como artefacto.
2. validate-php81 — descargar el artefacto, instalarlo y probarlo en una matriz de PHP 8.1, 8.2, 8.3 y 8.4.
3. release-php81 — descargar el artefacto, confirmar y etiquetar el árbol generado, comprimirlo excluyendo vendor/ y .git/, y publicar una release de GitHub con el archivo adjunto.

Vía de PHP 7.4

1. build-php74 — extraer las herramientas de compilación en la rama PHP74, aprovisionar PHP 8.5, clonar solo el repositorio de origen del núcleo en la etiqueta, ejecutar scripts/build.php --target=php74, cambiar a PHP 7.4 y comprobar la sintaxis de la salida con PHP 7.4.
2. validate-php74 — instalar y probar en una matriz de PHP 7.4 y 8.0.
3. release-php74 — comprimir solo la salida del núcleo y adjuntarla a la misma release como un segundo archivo.

Verificado con las definiciones de trabajos y las matrices de build.yml.

Las dos vías comparten una única release de GitHub. La vía de PHP 8.1 la crea, y la vía de PHP 7.4 adjunta su archivo a la misma etiqueta. El grupo de concurrency backport-build con cancel-in-progress: false serializa las compilaciones para que dos publicaciones de origen no puedan provocar una condición de carrera.

Operación del flujo

Activación de una compilación

Normalmente, una compilación se activa de forma automática cuando la organización de origen publica una release. Para recompilar una etiqueta concreta de forma manual, despachar build.yml con la etiqueta como entrada (por ejemplo v2.0.0). El token de despacho es secrets.BACKPORT_TRIGGER_TOKEN, y autoriza la clonación del repositorio de origen. Verificado en build.yml (workflow_dispatch.inputs.tag, GH_TOKEN).

Interpretación de una compilación fallida

El script de compilación se detiene en la primera etapa que falla e imprime el nombre de la etapa y el error. Las cinco etapas son fusión, Rector, generación de composer.json, copia de activos y validación. Si falla el paso de comprobación de sintaxis posterior a la compilación, Rector produjo una salida que el entorno de ejecución de destino rechaza. Ese paso es la barrera que protege la publicación. Asociar el fallo con su causa en /integrations/backport/troubleshooting/.

Qué se publica

La release incluye como adjuntos los archivos de distribución comprimidos. El paquete se distribuye como etiquetas de versión, no como ramas. Los consumidores instalan nextpdf/backport (y, de forma opcional, nextpdf/backport-pro) desde el canal de publicación. El archivo comprimido excluye vendor/ y .git/. Verificado en build.yml (zip -r ... -x '*/vendor/*' '*/.git/*').

Versionado de la salida

El composer.json generado contiene la versión pasada en la línea de comandos (--version, o la etiqueta de despacho con la v inicial eliminada). El paquete Pro fija nextpdf/backport con la restricción de intercalación (caret) major.minor correspondiente. Verificado en scripts/adjust-composer.php (majorMinor(), generateProComposer()). Mantener alineadas la etiqueta de publicación de origen y la versión del backport para que el mapa replace se mantenga coherente.

Siguiente

• /integrations/backport/security-and-operations/ — el límite de confianza y la postura de la cadena de suministro del flujo.
• /integrations/backport/troubleshooting/ — referencia de fallos por etapa.