Menjalankan perkakas build backport dalam alur rilis

Perkakas build, bukan dependensi runtime. Halaman ini menjelaskan cara mengoperasikan alur rilis yang menghasilkan backport. Alur ini berjalan dalam continuous integration (CI), dan tidak pernah berjalan di aplikasi hilir.

Sekilas pandang

Jalur produksi menggunakan dua workflow. 0-ci.yml menjaga setiap perubahan di setiap branch permanen. Rilis sumber memicu build.yml, yang membangun dan merilis distribusi. Kedua workflow tersebut diverifikasi terhadap .github/workflows/.

Gerbang CI

0-ci.yml berjalan pada peristiwa push dan pull request untuk PHP74 dan PHP81. Workflow ini menjalankan tiga job berikut secara berurutan:

1. PHPStan (Build Tools) — composer analyse, pada level 10 untuk rector/rules dan scripts.
2. PHPUnit (Rector Rules) — composer test, suite fixture untuk ketiga aturan khusus.
3. Build Dry Run — composer build:dry, dijaga di belakang dua job pertama.

Peristiwa tepercaya menggunakan runner PHP yang di-host sendiri. Pull request dari fork dan Dependabot menggunakan runner yang di-host GitHub dengan PHP 8.5 yang sudah disediakan. Hal ini diverifikasi terhadap 0-ci.yml (ekspresi runs-on dan langkah kondisional setup-php). Model dua branch memastikan perubahan yang menyentuh kedua target tetap divalidasi secara independen pada pull request untuk branch masing-masing.

Alur rilis

build.yml adalah build produksi. Workflow ini berjalan pada peristiwa repository_dispatch bertipe source-release, atau secara manual melalui workflow_dispatch dengan masukan tag. Alur ini digerakkan oleh tag versi. Nomor versi mengikuti bentuk MAJOR.MINOR.PATCH untuk API publik yang dideklarasikan (Semantic Versioning 2.0.0 §2).

Jalur PHP 8.1

1. build-php81 — meng-checkout perkakas build, menyiapkan PHP 8.5, memasang dependensi build, mengkloning repositori sumber pada tag rilis, menjalankan scripts/build.php, mengalihkan runner ke PHP 8.1, memeriksa sintaks output/src pada PHP 8.1, lalu memasang paket yang dihasilkan dengan --no-dev. Job ini mengunggah keluaran sebagai artefak.
2. validate-php81 — mengunduh artefak, lalu memasang dan mengujinya pada matriks PHP 8.1, 8.2, 8.3, dan 8.4.
3. release-php81 — mengunduh artefak, melakukan commit dan membuat tag pada pohon yang dihasilkan, membuat arsip zip yang mengecualikan vendor/ dan .git/, lalu menerbitkan rilis GitHub dengan arsip terlampir.

Jalur PHP 7.4

1. build-php74 — meng-checkout perkakas build pada branch PHP74, menyiapkan PHP 8.5, hanya mengkloning repositori sumber inti pada tag, menjalankan scripts/build.php --target=php74, beralih ke PHP 7.4, dan memeriksa sintaks keluaran pada PHP 7.4.
2. validate-php74 — memasang dan menguji pada matriks PHP 7.4 dan 8.0.
3. release-php74 — membuat arsip zip dari keluaran khusus inti dan melampirkannya ke rilis yang sama sebagai arsip kedua.

Alur ini diverifikasi terhadap definisi job dan matriks build.yml.

Kedua jalur berbagi satu rilis GitHub. Jalur PHP 8.1 membuat rilis, sedangkan jalur PHP 7.4 melampirkan arsipnya ke tag yang sama. Grup concurrency bernama backport-build dengan cancel-in-progress: false menjalankan build satu per satu, sehingga dua rilis sumber tidak dapat saling bertabrakan.

Mengoperasikan alur

Memicu build

Build biasanya dimulai secara otomatis ketika organisasi sumber menerbitkan rilis. Untuk membangun ulang tag tertentu secara manual, lakukan dispatch build.yml dengan masukan tag, misalnya v2.0.0. Token dispatch adalah secrets.BACKPORT_TRIGGER_TOKEN, dan token tersebut memberi otorisasi untuk mengkloning repositori sumber. Hal ini diverifikasi terhadap build.yml (workflow_dispatch.inputs.tag, GH_TOKEN).

Membaca build yang gagal

Skrip build berhenti pada tahap pertama yang gagal dan mencetak nama tahap beserta galatnya. Kelima tahap tersebut adalah merge, Rector, pembuatan composer.json, penyalinan aset, dan validasi. Jika langkah pemeriksaan sintaks setelah build gagal, berarti Rector menghasilkan keluaran yang ditolak oleh runtime target. Langkah ini melindungi rilis. Petakan kegagalan tersebut ke penyebabnya di /integrations/backport/troubleshooting/.

Apa yang diterbitkan

Rilis mencakup arsip distribusi dalam bentuk zip. Paket didistribusikan sebagai tag versi, bukan branch. Konsumen memasang nextpdf/backport (dan secara opsional nextpdf/backport-pro) dari saluran rilis. Arsip mengecualikan vendor/ dan .git/. Hal ini diverifikasi terhadap build.yml (zip -r ... -x '*/vendor/*' '*/.git/*').

Memberi versi pada keluaran

composer.json yang dihasilkan memuat versi yang diteruskan melalui baris perintah (--version, atau tag dispatch dengan awalan v dihilangkan). Paket Pro menyematkan nextpdf/backport ke batasan caret major.minor yang sesuai. Hal ini diverifikasi terhadap scripts/adjust-composer.php (majorMinor(), generateProComposer()). Jaga agar tag rilis sumber dan versi backport tetap selaras sehingga peta replace tetap konsisten.

Selanjutnya

• /integrations/backport/security-and-operations/ — batas kepercayaan alur dan postur rantai pasok.
• /integrations/backport/troubleshooting/ — referensi kegagalan di setiap tahap.