Guida per sviluppatori del Backport Builder

In breve

Il Backport Builder è un progetto di release engineering. Trattare i repository di origine come input, gli alberi generati come output e le regole Rector personalizzate come logica di build coperta da test.

Usare questa guida per gestire le regole di downgrade, i metadati dei pacchetti generati, i controlli del runtime di destinazione o l’automazione delle release relativa a nextpdf/backport-builder.

Confine architetturale

Livello	Di proprietà di	Responsabilità	Da non inserire qui
Repository di origine	Repository di prodotto	Codice sorgente PHP autorevole e relativi test.	Modifiche di downgrade generate.
Script di build	`nextpdf/backport-builder`	Unire le fonti, eseguire le trasformazioni, scrivere i metadati, convalidare l’output.	Logica applicativa di runtime.
Configurazione Rector	`nextpdf/backport-builder`	Criteri di downgrade specifici per destinazione.	Assunzioni cross-target senza test.
Regole Rector personalizzate	`nextpdf/backport-builder`	Trasformazioni sintattiche specifiche del progetto.	Riscritture ampie e non testate.
Pacchetti generati	Output della build	Artefatti installabili su runtime meno recenti.	Patch manuali alla fonte di verità.

Ciclo di vita della build

Fase	Comportamento	Azione dello sviluppatore
Checkout dell’origine	Il workflow di release esegue il checkout dei repository di origine sul tag di destinazione.	Mantenere allineati i riferimenti di origine tra i pacchetti.
Convalida del contratto	`ValidateBuildContract::run()` verifica le assunzioni della build.	Considerare un errore del contratto come bloccante per la release.
Unione	`MergeSources::run()` assembla l’albero del pacchetto di destinazione.	Verificare l’ambito di destinazione prima di eseguire Rector.
Trasformazione	Le configurazioni Rector e le regole personalizzate effettuano il downgrade della sintassi.	Aggiungere fixture di test per ogni modifica a una regola.
Adeguamento di Composer	`AdjustComposer` scrive i metadati del pacchetto generato e le mappe replace.	Convalidare nome del pacchetto, versione, licenza e vincoli.
Convalida del runtime	L’output generato viene sottoposto a controllo di sintassi e a test sulle versioni PHP di destinazione.	Considerare un errore sul runtime di destinazione come bloccante per la release.
Release	Gli archivi vengono allegati a una release.	Non applicare patch all’output generato come se fosse la fonte di verità.

Workflow del repository consigliato

Elemento di lavoro	Fonte di verità	Criteri per l’output generato
Uso delle funzionalità PHP	Repository di origine principale.	Le regole di backport adattano la funzionalità.
Vincoli delle dipendenze	Metadati del `composer.json` di origine e script di adeguamento.	Il file `composer.json` generato deve essere riproducibile.
Downgrade della sintassi	Configurazione Rector e regole personalizzate.	Il codice sorgente generato non deve essere modificato manualmente.
Supporto del runtime	Branch di destinazione e matrice CI.	La build deve riuscire con il PHP di destinazione.
Note di release	Documentazione e automazione delle release.	Gli artefatti generati devono rimandare alla release di origine.

Modello di regola Rector personalizzata

Ogni regola personalizzata deve avere uno scopo circoscritto, metadati e copertura tramite fixture.

Metodo della regola	Scopo	Requisito di qualità
`getRuleDefinition()`	Documenta la trasformazione per gli strumenti Rector.	Includere un esempio before/after allineato al downgrade reale.
`getNodeTypes()`	Limita i nodi AST ispezionati dalla regola.	Mantenere l’elenco dei nodi il più piccolo possibile.
`refactor()`	Applica la trasformazione oppure restituisce il nodo invariato.	Lasciare invariati e gestire in modo deterministico i nodi non interessati.
Test fixture	Verifica l’output before/after.	Coprire l’input valido minimo e almeno un caso di skip.

<?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);
    }
}

Modello di comando di build

Usare esecuzioni dry-run durante lo sviluppo e la convalida dei release candidate. Usare l’output reale solo quando i riferimenti di origine e il branch di destinazione sono noti.

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 convalida del pacchetto generato deve essere eseguita sul runtime di destinazione, non soltanto sull’host di build moderno.

Punti di estensione

Punto di estensione	Usarlo per	Vincolo
File di configurazione Rector	Criteri di downgrade specifici per destinazione.	Tenere separate le corsie PHP 8.1 e PHP 7.4.
Regole Rector personalizzate	Trasformazioni di sintassi specifiche del progetto.	Devono avere metadati e test fixture.
Script di adeguamento di Composer	Identità del pacchetto generato.	Deve preservare la versione allineata a SemVer.
Script di unione	Selezione e modellazione dell’input dei pacchetti di origine.	Deve registrare le radici di origine e di output.
Workflow di build	Orchestrazione della release.	Deve convalidare l’output generato sul runtime di destinazione.

Workflow di sviluppo

Riprodurre la sintassi non supportata in una fixture minima.
Aggiungere o aggiornare una regola Rector personalizzata.
Aggiungere fixture before/after per la regola.
Eseguire la build dry-run.
Convalidare l’output generato sul runtime PHP di destinazione.
Applicare la stessa modifica logica a ciascun branch di destinazione permanente, quando necessario.
Mantenere gli artefatti di release riproducibili a partire dai tag di origine e dagli script di build.

Gestione degli errori

Errore	Dove deve essere gestito	Risposta consigliata
Repository di origine mancante	Fase di convalida del contratto o di unione.	Arrestare la build e correggere gli input di checkout.
Errore di parsing di Rector	Fase di trasformazione.	Ridurre il caso a una fixture e aggiornare la regola o la configurazione.
Mancata corrispondenza del `composer.json` generato	Fase di adeguamento di Composer.	Correggere lo script di generazione, non i metadati generati.
Errore di sintassi della destinazione	Convalida del runtime.	Bloccare la release finché la trasformazione non è corretta.
Origine Pro non disponibile	Configurazione della build.	Generare l’artefatto pubblico solo quando è la destinazione prevista.

Impostazioni predefinite sicure

Aspetto	Impostazione predefinita	Quando eseguire l’override
Output generato	Artefatto di sola lettura.	Non renderlo mai la fonte di verità.
Modello di branch	Branch di destinazione permanenti separati.	Mantenere le modifiche sincronizzate tramite pull request indipendenti.
Host di build	PHP moderno.	La convalida del runtime di destinazione determina comunque se la release è pronta.
Regole personalizzate	Piccole e supportate da fixture.	Evitare trasformazioni ampie senza esempi before/after espliciti.
Corsia PHP 7.4	Solo Core a meno che non sia supportato esplicitamente.	Non includere l’output Pro senza la convalida del runtime di destinazione.

Elenco di controllo dei test

I test sui metadati delle regole Rector istanziano ogni regola personalizzata.
I test tramite fixture coprono il codice before e after per ciascuna trasformazione.
La build dry-run viene eseguita prima dei job di release.
I controlli di sintassi del runtime di destinazione e i test del pacchetto vengono eseguiti sull’output generato.
I test sui metadati di Composer verificano nome del pacchetto, versione, vincoli, mappa replace e licenza.
I log di build includono percorsi di origine, percorso di destinazione, runtime di destinazione, stato dry-run e stato di inclusione di Pro.