De backport-builder uitvoeren in een release-pijplijn

Buildgereedschap, geen runtime-afhankelijkheid. Deze pagina legt uit hoe je de release-pijplijn bedient waarmee de backport wordt geproduceerd. De pijplijn draait in continuous integration (CI); nooit in een downstreamapplicatie.

In een oogopslag

Het productiepad bestaat uit twee workflows. 0-ci.yml bewaakt elke wijziging op elke vaste branch. Een source-release start build.yml, die de distributie bouwt en uitbrengt. Beide workflows worden gecontroleerd aan de hand van .github/workflows/.

De CI-poort

0-ci.yml draait bij push- en pull-request-events voor PHP74 en PHP81. De workflow voert drie jobs op volgorde uit:

1. PHPStan (Build Tools) — composer analyse, op niveau 10 voor rector/rules en scripts.
2. PHPUnit (Rector Rules) — composer test, de fixture-suites voor de drie aangepaste regels.
3. Build Dry Run — composer build:dry, afhankelijk van de eerste twee jobs.

Vertrouwde events gebruiken zelfgehoste PHP-runners. Pull requests vanuit forks en Dependabot gebruiken door GitHub gehoste runners waarop PHP 8.5 is geprovisioneerd. Dit wordt gecontroleerd aan de hand van 0-ci.yml (de runs-on-expressie en de voorwaardelijke setup-php-stap). Het twee-branchmodel bewaakt wijzigingen die beide targets raken, onafhankelijk via de pull request van elke branch.

De release-pijplijn

build.yml is de productiebuild. De workflow draait op een repository_dispatch-event van het type source-release, of handmatig via workflow_dispatch met een tag als invoer. De versietag stuurt de pijplijn aan. Een versienummer heeft de vorm MAJOR.MINOR.PATCH voor een gedeclareerde publieke API (Semantic Versioning 2.0.0 §2).

PHP 8.1-job

1. build-php81 — checkt het buildgereedschap uit, provisioneert PHP 8.5, installeert build-afhankelijkheden, kloont de bronrepository’s op de release-tag, voert scripts/build.php uit, schakelt de runner over naar PHP 8.1, controleert de syntaxis van output/src op PHP 8.1 en installeert vervolgens het geproduceerde pakket met --no-dev. De job uploadt de uitvoer als artifact.
2. validate-php81 — downloadt het artifact en installeert en test het daarna op een matrix van PHP 8.1, 8.2, 8.3 en 8.4.
3. release-php81 — downloadt het artifact, maakt een commit van de gegenereerde boom en tagt die, maakt een zip-archief dat vendor/ en .git/ uitsluit, en publiceert een GitHub-release waaraan het archief is gekoppeld.

PHP 7.4-job

1. build-php74 — checkt het buildgereedschap uit op de PHP74-branch, provisioneert PHP 8.5, kloont alleen de core-bronrepository op de tag, voert scripts/build.php --target=php74 uit, schakelt over naar PHP 7.4, en controleert de syntaxis van de uitvoer op PHP 7.4.
2. validate-php74 — installeert en test op een matrix van PHP 7.4 en 8.0.
3. release-php74 — maakt een zip-archief van de core-only-uitvoer en koppelt het als tweede archief aan dezelfde release.

Deze flow wordt gecontroleerd aan de hand van de job-definities en matrices van build.yml.

De twee jobs delen één GitHub-release. De PHP 8.1-job maakt de release en de PHP 7.4-job koppelt het eigen archief aan dezelfde tag. De concurrency-groep backport-build met cancel-in-progress: false voert builds één voor één uit, zodat twee source-releases niet met elkaar kunnen botsen.

De pijplijn bedienen

Een build starten

Een build start normaal gesproken automatisch wanneer de bronorganisatie een release publiceert. Om een specifieke tag handmatig opnieuw te bouwen, dispatch je build.yml met de tag als invoer, zoals v2.0.0. Het dispatch-token is secrets.BACKPORT_TRIGGER_TOKEN, en autoriseert het klonen van de bronrepository. Dit wordt gecontroleerd aan de hand van build.yml (workflow_dispatch.inputs.tag, GH_TOKEN).

Een mislukte build lezen

Het buildscript stopt bij de eerste falende fase en toont de naam van de fase en de fout. De vijf fasen zijn merge, Rector, het genereren van composer.json, asset-kopie en validatie. Als de syntaxiscontrolestap na de build mislukt, heeft Rector uitvoer geproduceerd die de doelruntime afwijst. Die stap beschermt de release. Koppel de mislukking aan de bijbehorende oorzaak in /integrations/backport/troubleshooting/.

Wat er wordt gepubliceerd

De release bevat gezipte distributiearchieven. Het pakket wordt geleverd via versietags, niet via branches. Consumenten installeren nextpdf/backport (en optioneel nextpdf/backport-pro) vanuit het release-kanaal. Het archief sluit vendor/ en .git/ uit. Dit wordt gecontroleerd aan de hand van build.yml (zip -r ... -x '*/vendor/*' '*/.git/*').

De uitvoer versioneren

De geproduceerde composer.json bevat de versie die via de opdrachtregel is meegegeven (--version, of de dispatch-tag zonder de voorafgaande v). Het Pro-pakket pint nextpdf/backport vast op de overeenkomstige major.minor-caretbeperking. Dit wordt gecontroleerd aan de hand van scripts/adjust-composer.php (majorMinor(), generateProComposer()). Houd de source-release-tag en de backportversie op elkaar afgestemd, zodat de replace-map consistent blijft.

Vervolg

• /integrations/backport/security-and-operations/ — de vertrouwensgrens van de pijplijn en de supply-chainhouding.
• /integrations/backport/troubleshooting/ — foutreferentie voor elke fase.