Panduan Pengembang Backport Builder

Sekilas

Backport Builder adalah proyek rekayasa rilis. Perlakukan repositori sumber sebagai input, pohon yang dihasilkan sebagai output, dan aturan Rector khusus sebagai logika build yang teruji.

Gunakan panduan ini saat Anda memelihara aturan downgrade, metadata paket yang dihasilkan, pemeriksaan target-runtime, atau otomatisasi rilis untuk nextpdf/backport-builder.

Batasan arsitektur

Lapisan	Dimiliki oleh	Tanggung jawab	Jangan letakkan di sini
Repositori sumber	Repo produk	Sumber dan pengujian PHP yang menjadi otoritas.	Suntingan downgrade yang dihasilkan.
Skrip build	`nextpdf/backport-builder`	Menggabungkan sumber, menjalankan transformasi, menulis metadata, dan memvalidasi output.	Logika aplikasi runtime.
Konfigurasi Rector	`nextpdf/backport-builder`	Kebijakan downgrade spesifik target.	Asumsi lintas target tanpa pengujian.
Aturan Rector khusus	`nextpdf/backport-builder`	Transformasi sintaksis spesifik proyek.	Penulisan ulang berskala luas yang belum teruji.
Paket yang dihasilkan	Output build	Artefak yang dapat dipasang untuk runtime lama.	Patch manual pada source-of-truth.

Siklus hidup build

Tahap	Perilaku	Tindakan pengembang
Checkout sumber	Alur kerja rilis melakukan checkout repositori sumber pada tag target.	Tetap selaraskan ref sumber di seluruh paket.
Validasi kontrak	`ValidateBuildContract::run()` memeriksa asumsi build.	Perlakukan kontrak yang gagal sebagai penghalang rilis.
Penggabungan	`MergeSources::run()` menyusun pohon paket target.	Verifikasi cakupan target sebelum menjalankan Rector.
Transformasi	Konfigurasi Rector dan aturan khusus melakukan downgrade sintaksis.	Tambahkan pengujian fixture untuk setiap perubahan aturan.
Penyesuaian Composer	`AdjustComposer` menulis metadata paket yang dihasilkan dan peta replace.	Validasikan nama paket, versi, lisensi, dan batasan (constraint).
Validasi runtime	Output yang dihasilkan diperiksa sintaksisnya dan diuji di versi PHP target.	Perlakukan kegagalan target-runtime sebagai penghalang rilis.
Rilis	Arsip dilampirkan ke rilis.	Jangan menambal output yang dihasilkan untuk dijadikan source of truth.

Alur kerja repositori yang disarankan

Item pekerjaan	Source of truth	Kebijakan output yang dihasilkan
Penggunaan fitur PHP	Repo sumber utama.	Aturan backport mengadaptasi fitur tersebut.
Batasan dependensi	Metadata `composer.json` sumber beserta skrip penyesuaian.	`composer.json` yang dihasilkan harus dapat direproduksi.
Downgrade sintaksis	Konfigurasi Rector dan aturan khusus.	Sumber yang dihasilkan tidak boleh disunting secara manual.
Dukungan runtime	Branch target dan matriks CI.	Build harus lulus di PHP target.
Catatan rilis	Dokumentasi dan otomatisasi rilis.	Artefak yang dihasilkan harus memiliki tautan balik ke rilis sumber.

Pola aturan Rector khusus

Setiap aturan khusus harus memiliki tujuan yang terfokus, metadata, dan cakupan fixture.

Metode aturan	Tujuan	Persyaratan kualitas
`getRuleDefinition()`	Mendokumentasikan transformasi untuk perkakas Rector.	Sertakan contoh before/after yang sesuai dengan downgrade sebenarnya.
`getNodeTypes()`	Membatasi node AST yang diperiksa oleh aturan.	Jaga agar daftar node sekecil mungkin.
`refactor()`	Menerapkan transformasi atau mengembalikan node tanpa perubahan.	Biarkan node yang tidak terkait tetap tidak berubah dan hasilnya deterministik.
Pengujian fixture	Memverifikasi output before/after.	Cakup input valid terkecil dan setidaknya satu kasus yang dilewati (skip).

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

Pola perintah build

Gunakan dry run selama pengembangan dan saat memvalidasi kandidat rilis. Tulis output sebenarnya hanya setelah ref sumber dan branch target diketahui.

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

Jalankan validasi paket yang dihasilkan di runtime target, bukan hanya di host build modern.

Titik ekstensi

Titik ekstensi	Gunakan untuk	Batasan
File konfigurasi Rector	Kebijakan downgrade spesifik target.	Pisahkan jalur PHP 8.1 dan PHP 7.4.
Aturan Rector khusus	Transformasi sintaksis spesifik proyek.	Harus memiliki metadata dan pengujian fixture.
Skrip penyesuaian Composer	Identitas paket yang dihasilkan.	Harus menjaga versioning tetap selaras dengan SemVer.
Skrip penggabungan	Memilih dan menyusun input paket sumber.	Harus mencatat root sumber dan root output.
Alur kerja build	Orkestrasi rilis.	Harus memvalidasi output yang dihasilkan di runtime target.

Alur kerja pengembangan

Buat reproduksi sintaksis yang tidak didukung dalam fixture minimal.
Tambahkan atau perbarui aturan Rector khusus.
Tambahkan fixture before/after untuk aturan tersebut.
Jalankan dry build.
Validasikan output yang dihasilkan di runtime PHP target.
Terapkan perubahan logis yang sama ke setiap branch target permanen bila diperlukan.
Jaga agar artefak rilis tetap dapat direproduksi dari tag sumber dan skrip build.

Penanganan kegagalan

Kegagalan	Tempat penanganan	Respons yang disarankan
Repo sumber tidak ada	Tahap validasi kontrak atau penggabungan.	Hentikan build dan perbaiki input checkout.
Kegagalan parse Rector	Tahap transformasi.	Sederhanakan menjadi fixture lalu perbarui aturan atau konfigurasi.
`composer.json` yang dihasilkan tidak sesuai	Tahap penyesuaian Composer.	Perbaiki skrip build, bukan metadata yang dihasilkan.
Kegagalan sintaksis target	Validasi runtime.	Blokir rilis hingga transformasi diperbaiki.
Sumber Pro tidak tersedia	Konfigurasi build.	Build artefak publik hanya jika memang itu target yang dituju.

Default yang aman

Perhatian	Default	Kapan harus menggantinya
Output yang dihasilkan	Artefak hanya-baca.	Jangan pernah menjadikannya source of truth.
Model branch	Branch target permanen yang terpisah.	Jaga agar perubahan tetap tersinkronisasi melalui pull request independen.
Host build	PHP modern.	Validasi runtime target tetap menentukan kesiapan rilis.
Aturan khusus	Kecil dan didukung oleh fixture.	Hindari transformasi berskala luas tanpa contoh before/after yang eksplisit.
Jalur PHP 7.4	Hanya Core, kecuali didukung secara eksplisit.	Jangan sertakan output Pro tanpa validasi target-runtime.

Daftar periksa pengujian

Pengujian metadata aturan Rector menginstansiasi setiap aturan khusus.
Pengujian fixture mencakup kode before dan after untuk setiap transformasi.
Dry build dijalankan sebelum job rilis.
Pemeriksaan sintaksis runtime target dan pengujian paket dijalankan terhadap output yang dihasilkan.
Pengujian metadata Composer memastikan nama paket, versi, batasan, peta replace, dan lisensi.
Log build menyertakan path sumber, path target, runtime target, status dry-run, dan status penyertaan Pro.