Guía para desarrolladores de Backport Builder

De un vistazo

Backport Builder es un proyecto de ingeniería de versiones. Trata los repositorios de origen como entradas, los árboles generados como salidas y las reglas personalizadas de Rector como lógica de compilación probada.

Usar esta guía al mantener reglas de downgrade, metadatos de paquetes generados, comprobaciones del runtime de destino o automatización de versiones en torno a nextpdf/backport-builder.

Límites de la arquitectura

Capa	Propiedad de	Responsabilidad	No pongas aquí
Repositorios de origen	Repositorios de producto	Código fuente PHP autoritativo y pruebas.	Ediciones de downgrade generadas.
Scripts de compilación	`nextpdf/backport-builder`	Fusionan el origen, ejecutan las transformaciones, escriben los metadatos y validan la salida.	Lógica de aplicación en runtime.
Configuración de Rector	`nextpdf/backport-builder`	Política de downgrade específica del destino.	Suposiciones entre destinos sin pruebas.
Reglas personalizadas de Rector	`nextpdf/backport-builder`	Transformaciones de sintaxis específicas del proyecto.	Reescrituras amplias sin pruebas.
Paquetes generados	Salida de compilación	Artefactos instalables para runtimes antiguos.	Parches manuales en la fuente de la verdad.

Ciclo de vida de la compilación

Etapa	Comportamiento	Acción del desarrollador
Checkout del origen	El flujo de trabajo de versión hace checkout de los repositorios de origen en la etiqueta de destino.	Mantener alineadas las referencias de origen entre los paquetes.
Validación del contrato	`ValidateBuildContract::run()` comprueba las suposiciones de compilación.	Trata un contrato fallido como un bloqueo de la versión.
Fusión	`MergeSources::run()` ensambla el árbol del paquete de destino.	Verifica el alcance del destino antes de ejecutar Rector.
Transformación	Las configuraciones de Rector y las reglas personalizadas hacen downgrade de la sintaxis.	Añade pruebas de fixtures para cada cambio de regla.
Ajuste de Composer	`AdjustComposer` escribe los metadatos del paquete generado y los mapas de reemplazo.	Valida los nombres de paquete, la versión, la licencia y las restricciones.
Validación en runtime	La salida generada se comprueba sintácticamente y se prueba en las versiones de PHP de destino.	Trata un fallo del runtime de destino como un bloqueo de la versión.
Versión	Los archivos comprimidos se adjuntan a una versión.	No parchear la salida generada como fuente de la verdad.

Flujo de trabajo recomendado del repositorio

Elemento de trabajo	Fuente de la verdad	Política de la salida generada
Uso de características de PHP	Repositorio de origen principal.	Las reglas de backport adaptan la característica.
Restricciones de dependencias	Metadatos del `composer.json` de origen más el script de ajuste.	El `composer.json` generado debe ser reproducible.
Downgrade de sintaxis	Configuración de Rector y reglas personalizadas.	El código fuente generado no debe editarse manualmente.
Compatibilidad con runtime	Rama de destino y matriz de CI.	La compilación debe pasar en el PHP de destino.
Notas de la versión	Documentación y automatización de versiones.	Los artefactos generados deben enlazar de nuevo con la versión de origen.

Patrón para reglas personalizadas de Rector

Cada regla personalizada debe tener un propósito acotado, metadatos y cobertura mediante fixtures.

Método de la regla	Propósito	Requisito de calidad
`getRuleDefinition()`	Documenta la transformación para las herramientas de Rector.	Incluye una muestra before/after que coincida con el downgrade real.
`getNodeTypes()`	Limita los nodos del AST que inspecciona la regla.	Mantén la lista de nodos lo más pequeña posible.
`refactor()`	Aplica la transformación o devuelve el nodo sin cambios.	Deja intactos y de forma determinista los nodos no relacionados.
Prueba de fixture	Verifica la salida before/after.	Cubre la entrada válida más pequeña y al menos un caso que se omite.

<?php

final class ExampleDowngradeRector extends AbstractRector
{
    public function getNodeTypes(): array
    {
        return [SomeNode::class];
    }

    public function refactor(Node $node): ?Node
    {
        if (!$node instanceof SomeNode) {
            return null;
        }

        return $this->rewriteNode($node);
    }
}

Patrón de comando de compilación

Usar ejecuciones en seco durante el desarrollo y la validación de candidatas a versión. Usar la salida real solo cuando se conozcan las referencias de origen y la rama de destino.

composer build:dry
php scripts/build.php --version=2.0.0 --target=php81 --dry-run
php scripts/build.php --version=2.0.0 --target=php74 --no-pro

La validación del paquete generado debe ejecutarse en el runtime de destino, no solo en el host de compilación moderno.

Puntos de extensión

Punto de extensión	Úsalo para	Restricción
Archivos de configuración de Rector	Política de downgrade específica del destino.	Mantener separados los carriles de PHP 8.1 y PHP 7.4.
Reglas personalizadas de Rector	Transformaciones de sintaxis específicas del proyecto.	Deben tener metadatos y pruebas de fixtures.
Script de ajuste de Composer	Identidad del paquete generado.	Debe preservar el versionado alineado con SemVer.
Script de fusión	Selección y modelado de la entrada de paquetes de origen.	Debe registrar las raíces de origen y las raíces de salida.
Flujo de trabajo de compilación	Orquestación de versiones.	Debe validar la salida generada en el runtime de destino.

Flujo de trabajo de desarrollo

Reproducir la sintaxis no compatible en un fixture mínimo.
Añadir o actualizar una regla personalizada de Rector.
Añadir fixtures before/after para la regla.
Ejecutar la compilación en seco.
Validar la salida generada en el runtime de PHP de destino.
Aplicar el mismo cambio lógico a cada rama de destino permanente cuando sea necesario.
Mantener los artefactos de versión reproducibles a partir de las etiquetas de origen y los scripts de compilación.

Manejo de fallos

Fallo	Dónde debe manejarse	Respuesta recomendada
Falta el repositorio de origen	Etapa de validación del contrato o de fusión.	Detener la compilación y corregir las entradas del checkout.
Fallo de análisis de Rector	Etapa de transformación.	Reducirlo a un fixture y actualizar la regla o la configuración.
Discrepancia del `composer.json` generado	Etapa de ajuste de Composer.	Corrige el script de generación, no los metadatos generados.
Fallo de sintaxis de destino	Validación en runtime.	Bloquea la versión hasta que se corrija la transformación.
Origen Pro no disponible	Configuración de compilación.	Compila el artefacto público solo cuando ese sea el destino previsto.

Valores predeterminados seguros

Aspecto	Predeterminado	Cuándo anularlo
Salida generada	Artefacto de solo lectura.	Nunca convertirla en la fuente de la verdad.
Modelo de ramas	Ramas de destino permanentes separadas.	Mantener los cambios sincronizados mediante pull requests independientes.
Host de compilación	PHP moderno.	La validación del runtime de destino sigue decidiendo si la versión está lista.
Reglas personalizadas	Pequeñas y respaldadas por fixtures.	Evitar las transformaciones amplias sin ejemplos before/after explícitos.
Carril de PHP 7.4	Solo el core, salvo que se admita explícitamente.	No incluir la salida Pro sin validación del runtime de destino.

Lista de verificación de pruebas

Las pruebas de metadatos de reglas de Rector instancian cada regla personalizada.
Las pruebas de fixtures cubren el código antes y después de cada transformación.
La compilación en seco se ejecuta antes de los jobs de versión.
Las comprobaciones de sintaxis del runtime de destino y las pruebas de paquete se ejecutan sobre la salida generada.
Las pruebas de metadatos de Composer verifican el nombre del paquete, la versión, las restricciones, el mapa de reemplazo y la licencia.
Los logs de compilación incluyen las rutas de origen, la ruta de destino, el runtime de destino, el estado de la ejecución en seco y el estado de inclusión de Pro.