Przewodnik dla deweloperów Backport Builder

W skrócie

Backport Builder jest projektem inżynierii wydań. Repozytoria źródłowe traktuj jako dane wejściowe, wygenerowane drzewa jako dane wyjściowe, a niestandardowe reguły Rector jako przetestowaną logikę kompilacji.

Sięgaj do tego przewodnika, gdy utrzymujesz reguły obniżania wersji, metadane generowanych pakietów, kontrole środowiska docelowego lub automatyzację wydań dla nextpdf/backport-builder.

Granica architektury

Warstwa	Należy do	Odpowiedzialność	Nie umieszczaj tu
Repozytoria źródłowe	Repozytoria produktu	Wiarygodne źródło kodu PHP i testów.	Wygenerowane zmiany obniżające wersję.
Skrypty kompilacji	`nextpdf/backport-builder`	Scalają źródła, uruchamiają transformacje, zapisują metadane i weryfikują dane wyjściowe.	Logika aplikacji w czasie wykonywania.
Konfiguracja Rector	`nextpdf/backport-builder`	Reguły obniżania wersji właściwe dla środowiska docelowego.	Niesprawdzone założenia obejmujące wiele środowisk docelowych.
Niestandardowe reguły Rector	`nextpdf/backport-builder`	Transformacje składni właściwe dla projektu.	Szerokie, nieprzetestowane przepisania.
Wygenerowane pakiety	Dane wyjściowe kompilacji	Instalowalne artefakty dla starszych środowisk uruchomieniowych.	Ręczne poprawki traktowane jako wiarygodne źródło.

Cykl życia kompilacji

Etap	Zachowanie	Działanie dewelopera
Pobranie źródła	Proces wydania pobiera repozytoria źródłowe dla tagu docelowego.	Utrzymuj spójne referencje źródłowe we wszystkich pakietach.
Walidacja kontraktu	`ValidateBuildContract::run()` sprawdza założenia kompilacji.	Traktuj niespełniony kontrakt jako blokujący wydanie.
Scalanie	`MergeSources::run()` tworzy drzewo pakietu docelowego.	Zweryfikuj zakres docelowy przed uruchomieniem Rector.
Transformacja	Konfiguracje Rector i niestandardowe reguły obniżają składnię do wymaganej wersji.	Dodawaj testy z danymi przykładowymi do każdej zmiany reguły.
Dostosowanie Composer	`AdjustComposer` zapisuje metadane wygenerowanego pakietu i mapy zastąpień.	Zweryfikuj nazwy pakietów, wersje, licencje i ograniczenia.
Walidacja środowiska uruchomieniowego	Wygenerowane dane wyjściowe są sprawdzane pod kątem składni i testowane na docelowych wersjach PHP.	Traktuj błąd w środowisku docelowym jako blokujący wydanie.
Wydanie	Do wydania dołączane są archiwa.	Nie traktuj wygenerowanych danych wyjściowych jako wiarygodnego źródła i nie poprawiaj ich ręcznie.

Zalecany przepływ pracy w repozytorium

Element pracy	Wiarygodne źródło	Zasady dotyczące wygenerowanych danych wyjściowych
Użycie funkcji PHP	Główne repozytorium źródłowe.	Reguły backportu dostosowują użycie funkcji.
Ograniczenia zależności	Metadane źródłowe `composer.json` oraz skrypt dostosowujący.	Wygenerowany `composer.json` musi być odtwarzalny.
Obniżanie wersji składni	Konfiguracja Rector i niestandardowe reguły.	Wygenerowanego źródła nie należy edytować ręcznie.
Wsparcie środowiska uruchomieniowego	Gałąź docelowa i macierz CI.	Kompilacja musi przejść na docelowym PHP.
Informacje o wydaniu	Dokumentacja i automatyzacja wydań.	Wygenerowane artefakty powinny odsyłać do wydania źródłowego.

Wzorzec niestandardowej reguły Rector

Każda niestandardowa reguła powinna mieć wąsko określony cel, metadane i pokrycie danymi przykładowymi.

Metoda reguły	Cel	Wymaganie jakościowe
`getRuleDefinition()`	Dokumentuje transformację na potrzeby narzędzi Rector.	Dołącz próbkę before/after odpowiadającą rzeczywistemu obniżeniu wersji.
`getNodeTypes()`	Ogranicza węzły AST sprawdzane przez regułę.	Utrzymuj listę węzłów możliwie najkrótszą.
`refactor()`	Stosuje transformację lub zwraca węzeł bez zmian.	Niepowiązane węzły pozostaw bez zmian, a zachowanie utrzymuj deterministyczne.
Test z danymi przykładowymi	Weryfikuje dane wyjściowe before/after.	Uwzględnij najmniejsze prawidłowe dane wejściowe i co najmniej jeden przypadek pominięcia.

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

Wzorzec polecenia kompilacji

Używaj uruchomień próbnych podczas programowania i walidacji kandydata do wydania. Zapisuj rzeczywiste dane wyjściowe tylko wtedy, gdy referencje źródłowe i gałąź docelowa są ustalone.

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

Uruchamiaj walidację wygenerowanego pakietu w docelowym środowisku uruchomieniowym, a nie tylko na nowoczesnym hoście kompilacji.

Punkty rozszerzeń

Punkt rozszerzeń	Zastosowanie	Ograniczenie
Pliki konfiguracji Rector	Zasady obniżania wersji właściwe dla środowiska docelowego.	Utrzymuj oddzielne ścieżki dla PHP 8.1 i PHP 7.4.
Niestandardowe reguły Rector	Transformacje składni właściwe dla projektu.	Muszą mieć metadane i testy z danymi przykładowymi.
Skrypt dostosowujący Composer	Tożsamość wygenerowanego pakietu.	Musi zachować wersjonowanie zgodne z SemVer.
Skrypt scalający	Wybieranie i kształtowanie wejściowych pakietów źródłowych.	Musi rejestrować katalogi główne źródeł i katalogi główne danych wyjściowych.
Proces kompilacji	Orkiestracja wydania.	Musi walidować wygenerowane dane wyjściowe w docelowym środowisku uruchomieniowym.

Przepływ pracy programistycznej

Odtwórz nieobsługiwaną składnię w minimalnych danych przykładowych.
Dodaj lub zaktualizuj niestandardową regułę Rector.
Dodaj dane przykładowe before/after dla reguły.
Uruchom kompilację próbną.
Zwaliduj wygenerowane dane wyjściowe w docelowym środowisku uruchomieniowym PHP.
Zastosuj tę samą zmianę logiczną w każdej trwałej gałęzi docelowej, gdy jest to wymagane.
Dbaj o to, aby artefakty wydania były odtwarzalne na podstawie tagów źródłowych i skryptów kompilacji.

Obsługa awarii

Awaria	Gdzie obsłużyć	Zalecana reakcja
Brak repozytorium źródłowego	Etap walidacji kontraktu lub scalania.	Zatrzymaj kompilację i napraw dane wejściowe etapu pobierania.
Błąd parsowania Rector	Etap transformacji.	Sprowadź problem do danych przykładowych i zaktualizuj regułę lub konfigurację.
Wygenerowany `composer.json` jest niezgodny	Etap dostosowania Composer.	Napraw skrypt generujący, a nie wygenerowane metadane.
Awaria składni docelowej	Walidacja środowiska uruchomieniowego.	Zablokuj wydanie, dopóki transformacja nie zostanie poprawiona.
Niedostępne źródło Pro	Konfiguracja kompilacji.	Buduj artefakt publiczny tylko wtedy, gdy jest to zamierzony cel.

Bezpieczne ustawienia domyślne

Zagadnienie	Wartość domyślna	Kiedy zmienić
Wygenerowane dane wyjściowe	Artefakty tylko do odczytu.	Nigdy nie traktuj ich jako wiarygodnego źródła.
Model gałęzi	Oddzielne trwałe gałęzie docelowe.	Synchronizuj zmiany za pomocą osobnych pull requestów.
Host kompilacji	Nowoczesny PHP.	O gotowości do wydania nadal decyduje walidacja docelowego środowiska uruchomieniowego.
Niestandardowe reguły	Niewielkie i poparte danymi przykładowymi.	Unikaj szerokich transformacji bez jawnych przykładów before/after.
Ścieżka PHP 7.4	Tylko Core, chyba że jest jawnie obsługiwana.	Nie dołączaj danych wyjściowych Pro bez walidacji docelowego środowiska uruchomieniowego.

Lista kontrolna testów

Testy metadanych reguł Rector tworzą instancję każdej niestandardowej reguły.
Testy z danymi przykładowymi obejmują kod before/after dla każdej transformacji.
Kompilacja próbna jest uruchamiana przed zadaniami wydania.
Kontrole składni w docelowym środowisku uruchomieniowym i testy pakietów są uruchamiane na wygenerowanych danych wyjściowych.
Testy metadanych Composer sprawdzają nazwę pakietu, wersję, ograniczenia, mapę zastąpień i licencję.
Dzienniki kompilacji zawierają ścieżki źródłowe, ścieżkę docelową, docelowe środowisko uruchomieniowe, informację, czy uruchomienie było próbne, oraz status dołączenia Pro.