Uruchamianie generatora backportu w potoku wydań

To narzędzia kompilacji, nie zależność uruchomieniowa. Ta strona wyjaśnia, jak obsługiwać potok wydań, który wytwarza backport. Potok działa w środowisku ciągłej integracji (CI); nigdy nie działa w aplikacji odbiorczej.

W skrócie

Ścieżka produkcyjna korzysta z dwóch przepływów pracy. 0-ci.yml stanowi bramkę dla każdej zmiany w każdej utrzymywanej gałęzi. Wydanie ze źródła wyzwala build.yml, który kompiluje i wydaje dystrybucję. Oba przepływy pracy są sprawdzane na podstawie .github/workflows/.

Bramka CI

0-ci.yml uruchamia się przy zdarzeniach push i pull request dla PHP74 i PHP81. Wykonuje kolejno trzy zadania:

1. PHPStan (Build Tools) — composer analyse, poziom 10 dla rector/rules i scripts.
2. PHPUnit (Rector Rules) — composer test, zestawy testów opartych na danych wejściowych dla trzech reguł niestandardowych.
3. Build Dry Run — composer build:dry, uzależnione od dwóch pierwszych zadań.

Zaufane zdarzenia korzystają z własnych modułów uruchamiających PHP. Pull requesty z forków oraz Dependabot korzystają z modułów uruchamiających hostowanych przez GitHub z udostępnionym PHP 8.5. Potwierdza to 0-ci.yml (wyrażenie runs-on oraz warunkowy krok setup-php). Model dwóch gałęzi niezależnie przepuszcza przez bramkę zmiany dotyczące obu celów w pull requestach do każdej z tych gałęzi.

Potok wydawniczy

build.yml to produkcyjny przepływ kompilacji. Uruchamia się przy zdarzeniu repository_dispatch typu source-release albo ręcznie przez workflow_dispatch z danymi wejściowymi tagu. Tag wersji steruje potokiem. Numer wersji ma postać MAJOR.MINOR.PATCH w odniesieniu do zadeklarowanego publicznego API (Semantic Versioning 2.0.0 §2).

Tor PHP 8.1

1. build-php81 — pobiera narzędzia kompilacji, udostępnia PHP 8.5, instaluje zależności potrzebne do kompilacji, klonuje repozytoria źródłowe dla tagu wydania, uruchamia scripts/build.php, przełącza moduł uruchamiający na PHP 8.1, sprawdza składnię output/src w PHP 8.1, a następnie instaluje wytworzony pakiet z --no-dev. Przesyła wynik jako artefakt.
2. validate-php81 — pobiera artefakt, a następnie instaluje go i testuje na macierzy PHP 8.1, 8.2, 8.3 i 8.4.
3. release-php81 — pobiera artefakt, zatwierdza i taguje wygenerowane drzewo, tworzy archiwum zip, które wyklucza vendor/ i .git/, oraz publikuje wydanie w GitHub z dołączonym archiwum.

Tor PHP 7.4

1. build-php74 — pobiera narzędzia kompilacji z gałęzi PHP74, udostępnia PHP 8.5, klonuje tylko podstawowe repozytorium źródłowe dla tagu, uruchamia scripts/build.php --target=php74, przełącza się na PHP 7.4 i sprawdza składnię wyniku w PHP 7.4.
2. validate-php74 — instaluje i testuje na macierzy PHP 7.4 i 8.0.
3. release-php74 — tworzy archiwum zip z wyniku obejmującego tylko rdzeń i dołącza je do tego samego wydania jako drugie archiwum.

Ten przepływ jest sprawdzany względem definicji zadań i macierzy w build.yml.

Oba tory współdzielą jedno wydanie w GitHub. Tor PHP 8.1 tworzy wydanie, a tor PHP 7.4 dołącza swoje archiwum do tego samego tagu. Grupa concurrency o nazwie backport-build z cancel-in-progress: false uruchamia kompilacje po kolei, więc dwa wydania ze źródła nie mogą wejść w stan wyścigu.

Obsługa potoku

Wyzwalanie kompilacji

Kompilacja zwykle uruchamia się automatycznie, gdy organizacja źródłowa opublikuje wydanie. Aby ręcznie ponownie skompilować konkretny tag, uruchom build.yml z danymi wejściowymi tagu, takimi jak v2.0.0. Token wyzwalający to secrets.BACKPORT_TRIGGER_TOKEN; służy do autoryzacji klonowania repozytoriów źródłowych. Potwierdza to build.yml (workflow_dispatch.inputs.tag, GH_TOKEN).

Analiza nieudanej kompilacji

Skrypt kompilacji zatrzymuje się na pierwszym etapie zakończonym niepowodzeniem i wypisuje nazwę etapu oraz błąd. Pięć etapów to scalanie, Rector, generowanie composer.json, kopiowanie zasobów oraz walidacja. Jeśli krok sprawdzania składni po kompilacji zakończy się niepowodzeniem, Rector wytworzył wynik, który docelowe środowisko uruchomieniowe odrzuca. Ten krok chroni wydanie. Powiąż niepowodzenie z jego przyczyną w /integrations/backport/troubleshooting/.

Co jest publikowane

Wydanie obejmuje skompresowane archiwa dystrybucyjne. Pakiet jest dostarczany w postaci tagów wersji, a nie gałęzi. Odbiorcy instalują nextpdf/backport (oraz opcjonalnie nextpdf/backport-pro) z kanału wydań. Archiwum wyklucza vendor/ i .git/. Potwierdza to build.yml (zip -r ... -x '*/vendor/*' '*/.git/*').

Wersjonowanie wyniku

Wytworzony composer.json zawiera wersję przekazaną w wierszu poleceń (--version lub tag wyzwalający po usunięciu wiodącego v). Pakiet Pro przypina nextpdf/backport do odpowiadającego mu ograniczenia z daszkiem dla major.minor. Potwierdza to scripts/adjust-composer.php (majorMinor(), generateProComposer()). Utrzymuj zgodność tagu wydania źródłowego z wersją backportu, aby mapa replace pozostała spójna.

Dalej

• /integrations/backport/security-and-operations/ — granica zaufania potoku i postawa wobec łańcucha dostaw.
• /integrations/backport/troubleshooting/ — opis niepowodzeń na każdym etapie.