Ontwikkelaarsgids voor Backport Builder

In een oogopslag

Backport Builder is een project voor release engineering. Behandel bronrepository’s als invoer, gegenereerde bestandsstructuren als uitvoer en aangepaste Rector-regels als geteste buildlogica.

Gebruik deze gids wanneer je downgraderegels, gegenereerde pakketmetadata, target-runtimecontroles of release-automatisering voor nextpdf/backport-builder onderhoudt.

Architectuurgrens

Laag	Eigenaar	Verantwoordelijkheid	Hoort hier niet thuis
Bronrepository’s	Productrepo’s	Gezaghebbende PHP-broncode en tests.	Gegenereerde downgradewijzigingen.
Buildscripts	`nextpdf/backport-builder`	Bronnen samenvoegen, transformaties uitvoeren, metadata schrijven en uitvoer valideren.	Runtime-applicatielogica.
Rector-configuratie	`nextpdf/backport-builder`	Targetspecifiek downgradebeleid.	Targetoverschrijdende aannames zonder tests.
Aangepaste Rector-regels	`nextpdf/backport-builder`	Projectspecifieke syntactische transformaties.	Brede, ongeteste herschrijvingen.
Gegenereerde pakketten	Builduitvoer	Installeerbare artefacten voor oudere runtimes.	Handmatige patches op de source of truth.

Buildlevenscyclus

Fase	Gedrag	Actie voor ontwikkelaar
Bronnen uitchecken	De release-workflow checkt bronrepository’s uit op de target-tag.	Houd bronreferenties over alle pakketten heen op elkaar afgestemd.
Contractvalidatie	`ValidateBuildContract::run()` controleert de buildaannames.	Behandel een mislukt contract als release-blokkerend.
Samenvoegen	`MergeSources::run()` stelt de target-pakketstructuur samen.	Controleer de target-scope voordat Rector wordt uitgevoerd.
Transformeren	Rector-configuraties en aangepaste regels downgraden de syntaxis.	Voeg fixturetests toe voor elke regelwijziging.
Composer-aanpassing	`AdjustComposer` schrijft gegenereerde pakketmetadata en replace-maps.	Valideer pakketnamen, versies, licenties en constraints.
Runtimevalidatie	De gegenereerde uitvoer wordt gecontroleerd op syntaxis en getest op de target-PHP-versies.	Behandel een fout in de target-runtime als release-blokkerend.
Release	Archieven worden aan een release gekoppeld.	Patch de gegenereerde uitvoer niet als source of truth.

Aanbevolen repositoryworkflow

Werkitem	Source of truth	Beleid voor gegenereerde uitvoer
Gebruik van PHP-features	Hoofdbronrepo.	Backportregels passen de feature aan.
Afhankelijkheidsconstraints	Bronmetadata uit `composer.json` plus het aanpassingsscript.	De gegenereerde `composer.json` moet reproduceerbaar zijn.
Syntaxisdowngrade	Rector-configuratie en aangepaste regels.	Gegenereerde broncode mag niet handmatig worden bewerkt.
Runtime-ondersteuning	Target-branch en CI-matrix.	De build moet slagen op de target-PHP-runtime.
Releaseopmerkingen	Documentatie en release-automatisering.	Gegenereerde artefacten moeten terugverwijzen naar de bronrelease.

Patroon voor aangepaste Rector-regels

Elke aangepaste regel moet een nauw afgebakend doel, metadata en fixturedekking hebben.

Regelmethode	Doel	Kwaliteitseis
`getRuleDefinition()`	Documenteert de transformatie voor de Rector-tooling.	Voeg een before/after-voorbeeld toe dat overeenkomt met de werkelijke downgrade.
`getNodeTypes()`	Beperkt de AST-knooppunten die de regel inspecteert.	Houd de lijst met knooppunten zo klein mogelijk.
`refactor()`	Past de transformatie toe of geeft het knooppunt ongewijzigd terug.	Laat niet-gerelateerde knooppunten ongewijzigd en behoud deterministisch gedrag.
Fixturetest	Verifieert de before/after-uitvoer.	Dek de kleinste geldige invoer en ten minste één skip-geval af.

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

Patroon voor buildcommando’s

Gebruik dry runs tijdens de ontwikkeling en de validatie van releasekandidaten. Schrijf pas echte uitvoer wanneer de bronreferenties en de target-branch bekend zijn.

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

Valideer gegenereerde pakketten op de target-runtime, niet alleen op de moderne buildhost.

Uitbreidingspunten

Uitbreidingspunt	Gebruik voor	Constraint
Rector-configuratiebestanden	Targetspecifiek downgradebeleid.	Houd de PHP 8.1- en PHP 7.4-jobs gescheiden.
Aangepaste Rector-regels	Projectspecifieke syntactische transformaties.	Moet metadata en fixturetests hebben.
Composer-aanpassingsscript	Identiteit van het gegenereerde pakket.	Moet SemVer-conforme versievoering behouden.
Samenvoegscript	De invoer van het bronpakket selecteren en vormgeven.	Moet de bronroots en uitvoerroots loggen.
Buildworkflow	Release-orkestratie.	Moet de gegenereerde uitvoer valideren op de target-runtime.

Ontwikkelworkflow

Reproduceer de niet-ondersteunde syntaxis in een minimale fixture.
Voeg een aangepaste Rector-regel toe of werk deze bij.
Voeg before/after-fixtures toe voor de regel.
Voer de dry build uit.
Valideer de gegenereerde uitvoer op de target-PHP-runtime.
Pas dezelfde logische wijziging toe op elke permanente target-branch wanneer dat nodig is.
Houd releaseartefacten reproduceerbaar vanuit brontags en buildscripts.

Foutafhandeling

Fout	Waar deze moet worden afgehandeld	Aanbevolen reactie
Ontbrekende bronrepo	Contractvalidatie- of samenvoegfase.	Stop de build en corrigeer de checkout-invoer.
Rector-parsefout	Transformatiefase.	Herleid de fout tot een fixture en werk de regel of configuratie bij.
Gegenereerde `composer.json` komt niet overeen	Composer-aanpassingsfase.	Corrigeer het generatiescript, niet de gegenereerde metadata.
Target-syntaxisfout	Runtimevalidatie.	Blokkeer de release totdat de transformatie is gecorrigeerd.
Pro-bron niet beschikbaar	Buildconfiguratie.	Bouw alleen een publiek artefact als dat de bedoelde target is.

Veilige standaardwaarden

Aandachtspunt	Standaard	Wanneer overschrijven
Gegenereerde uitvoer	Alleen-lezen artefact.	Maak die nooit de source of truth.
Branchmodel	Afzonderlijke permanente target-branches.	Houd wijzigingen gesynchroniseerd via onafhankelijke pull requests.
Buildhost	Moderne PHP.	De target-runtimevalidatie bepaalt nog steeds de releasegereedheid.
Aangepaste regels	Klein en gedekt door fixtures.	Vermijd brede transformaties zonder expliciete before/after-voorbeelden.
PHP 7.4-job	Alleen Core, tenzij expliciet ondersteund.	Neem geen Pro-uitvoer op zonder target-runtimevalidatie.

Testchecklist

Metadatatests voor Rector-regels instantiëren elke aangepaste regel.
Fixturetests dekken de before- en after-code voor elke transformatie af.
De dry build draait vóór de release-jobs.
Syntaxiscontroles op de target-runtime en pakkettests draaien op de gegenereerde uitvoer.
Composer-metadatatests verifiëren de pakketnaam, versie, constraints, replace-map en licentie.
Buildlogs bevatten bronpaden, het target-pad, de target-runtime, de dry-run-status en de status van Pro-opname.