Entwicklerleitfaden für den Backport Builder

Auf einen Blick

Der Backport Builder ist ein Release-Engineering-Projekt. Behandeln Sie Quell-Repositorys als Eingabe, generierte Verzeichnisbäume als Ausgabe und eigene Rector-Regeln als getestete Build-Logik.

Verwenden Sie diesen Leitfaden, wenn Sie Downgrade-Regeln, generierte Paketmetadaten, Prüfungen der Ziellaufzeit oder die Release-Automatisierung rund um nextpdf/backport-builder pflegen.

Architekturgrenze

Schicht	Verantwortet von	Verantwortung	Gehört nicht hierher
Quell-Repositorys	Produkt-Repositorys	Maßgeblicher PHP-Quellcode einschließlich Tests.	Generierte Downgrade-Änderungen.
Build-Skripte	`nextpdf/backport-builder`	Quellcode zusammenführen, Transformationen ausführen, Metadaten schreiben, Ausgabe validieren.	Laufzeit-Anwendungslogik.
Rector-Konfiguration	`nextpdf/backport-builder`	Zielspezifische Downgrade-Richtlinie.	Ungetestete Annahmen über mehrere Ziele hinweg.
Eigene Rector-Regeln	`nextpdf/backport-builder`	Projektspezifische Syntaxtransformationen.	Breite, ungetestete Umschreibungen.
Generierte Pakete	Build-Ausgabe	Installierbare Artefakte für ältere Laufzeiten.	Manuelle Patches an der Quelle der Wahrheit.

Build-Lebenszyklus

Stufe	Verhalten	Entwickleraktion
Quell-Checkout	Der Release-Workflow checkt die Quell-Repositorys am Ziel-Tag aus.	Halten Sie die Quell-Refs paketübergreifend synchron.
Vertragsvalidierung	`ValidateBuildContract::run()` prüft die Build-Annahmen.	Behandeln Sie eine fehlgeschlagene Vertragsvalidierung als Release-Blocker.
Zusammenführen	`MergeSources::run()` setzt den Ziel-Paketbaum zusammen.	Prüfen Sie den Zielumfang, bevor Sie Rector ausführen.
Transformieren	Rector-Konfigurationen und eigene Regeln führen das Syntax-Downgrade durch.	Fügen Sie für jede Regeländerung Fixture-Tests hinzu.
Composer-Anpassung	`AdjustComposer` schreibt die generierten Paketmetadaten und Replace-Maps.	Validieren Sie Paketnamen, Version, Lizenz und Constraints.
Laufzeitvalidierung	Die generierte Ausgabe wird auf den Ziel-PHP-Versionen syntaktisch geprüft und getestet.	Behandeln Sie einen Fehlschlag auf der Ziellaufzeit als Release-Blocker.
Release	Archive werden an ein Release angehängt.	Patchen Sie die generierte Ausgabe nicht, als wäre sie die Quelle der Wahrheit.

Empfohlener Repository-Workflow

Arbeitspaket	Quelle der Wahrheit	Richtlinie für die generierte Ausgabe
Nutzung von PHP-Features	Haupt-Quell-Repository.	Backport-Regeln passen das Feature an.
Abhängigkeits-Constraints	Metadaten aus der Quell-`composer.json` plus Anpassungsskript.	Die generierte `composer.json` muss reproduzierbar sein.
Syntax-Downgrade	Rector-Konfiguration und eigene Regeln.	Generierter Quellcode sollte nicht manuell bearbeitet werden.
Laufzeit-Unterstützung	Ziel-Branch und CI-Matrix.	Der Build muss auf der Ziel-PHP-Laufzeit bestehen.
Release-Notes	Dokumentation und Release-Automatisierung.	Generierte Artefakte sollten auf das Quell-Release zurückverweisen.

Muster für eigene Rector-Regeln

Jede eigene Regel sollte einen klar umrissenen Zweck, Metadaten und Fixture-Abdeckung haben.

Regelmethode	Zweck	Qualitätsanforderung
`getRuleDefinition()`	Dokumentiert die Transformation für das Rector-Tooling.	Fügen Sie ein before/after-Beispiel hinzu, das dem tatsächlichen Downgrade entspricht.
`getNodeTypes()`	Begrenzt die AST-Knoten, die die Regel untersucht.	Halten Sie die Knotenliste so klein wie möglich.
`refactor()`	Wendet die Transformation an oder gibt den Knoten unverändert zurück.	Geben Sie nicht betroffene Knoten unverändert und deterministisch zurück.
Fixture-Test	Prüft die before/after-Ausgabe.	Decken Sie die kleinste gültige Eingabe und mindestens einen Skip-Fall ab.

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

Muster für den Build-Befehl

Nutzen Sie Dry-Runs während der Entwicklung und zur Validierung von Release-Kandidaten. Erzeugen Sie eine tatsächliche Ausgabe nur, wenn die Quell-Refs und der Ziel-Branch bekannt sind.

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

Die Validierung des generierten Pakets sollte auf der Ziellaufzeit stattfinden, nicht nur auf dem modernen Build-Host.

Erweiterungspunkte

Erweiterungspunkt	Verwenden Sie ihn für	Constraint
Rector-Konfigurationsdateien	Zielspezifische Downgrade-Richtlinie.	Halten Sie die Lanes für PHP 8.1 und PHP 7.4 getrennt.
Eigene Rector-Regeln	Projektspezifische Syntaxtransformationen.	Müssen Metadaten und Fixture-Tests enthalten.
Composer-Anpassungsskript	Identität des generierten Pakets.	Muss die SemVer-konforme Versionierung bewahren.
Merge-Skript	Auswahl und Aufbereitung der Quellpaket-Eingabe.	Muss Quell-Roots und Output-Roots protokollieren.
Build-Workflow	Release-Orchestrierung.	Muss die generierte Ausgabe auf der Ziellaufzeit validieren.

Entwicklungs-Workflow

Reproduzieren Sie die nicht unterstützte Syntax in einem minimalen Fixture.
Fügen Sie eine eigene Rector-Regel hinzu oder aktualisieren Sie sie.
Fügen Sie before/after-Fixtures für die Regel hinzu.
Führen Sie den Dry-Build aus.
Validieren Sie die generierte Ausgabe auf der Ziel-PHP-Laufzeit.
Wenden Sie bei Bedarf dieselbe logische Änderung auf jeden dauerhaften Ziel-Branch an.
Halten Sie die Release-Artefakte aus Quell-Tags und Build-Skripten reproduzierbar.

Fehlerbehandlung

Fehler	Wo er behandelt werden sollte	Empfohlene Reaktion
Fehlendes Quell-Repository	Vertragsvalidierung oder Merge-Stufe.	Stoppen Sie den Build und korrigieren Sie die Checkout-Eingaben.
Rector-Parsefehler	Transformationsstufe.	Reduzieren Sie den Fall auf ein Fixture und aktualisieren Sie die Regel oder Konfiguration.
Abweichung bei der generierten `composer.json`-Datei	Stufe der Composer-Anpassung.	Korrigieren Sie das Generierungsskript, nicht die generierten Metadaten.
Fehler in der Zielsyntax	Laufzeitvalidierung.	Blockieren Sie das Release, bis die Transformation korrigiert ist.
Pro-Quelle nicht verfügbar	Build-Konfiguration.	Erstellen Sie das öffentliche Artefakt nur, wenn dies das beabsichtigte Ziel ist.

Sichere Standardwerte

Aspekt	Standard	Wann abweichen
Generierte Ausgabe	Schreibgeschütztes Artefakt.	Machen Sie sie niemals zur Quelle der Wahrheit.
Branch-Modell	Getrennte, dauerhafte Ziel-Branches.	Halten Sie Änderungen über unabhängige Pull Requests synchron.
Build-Host	Modernes PHP.	Über die Release-Reife entscheidet weiterhin die Validierung auf der Ziellaufzeit.
Eigene Regeln	Klein und durch Fixtures abgesichert.	Vermeiden Sie breite Transformationen ohne explizite before/after-Beispiele.
PHP-7.4-Lane	Nur Core, sofern nicht ausdrücklich unterstützt.	Nehmen Sie keine Pro-Ausgabe ohne Validierung auf der Ziellaufzeit auf.

Test-Checkliste

Tests der Rector-Regel-Metadaten instanziieren jede eigene Regel.
Fixture-Tests decken für jede Transformation den Code vor und nach der Umwandlung ab.
Der Dry-Build läuft vor den Release-Jobs.
Syntaxprüfungen für die Ziellaufzeit und Pakettests werden auf der generierten Ausgabe ausgeführt.
Composer-Metadaten-Tests prüfen Paketname, Version, Constraints, Replace-Map und Lizenz.
Build-Logs enthalten Quellpfade, Zielpfad, Ziellaufzeit, Dry-Run-Status und den Status der Pro-Einbindung.