Backport Builder geliştirici kılavuzu

Genel bakış

Backport Builder bir sürüm mühendisliği projesidir. Kaynak depolarını girdi olarak, üretilen ağaçları çıktı olarak ve özel Rector kurallarını test edilmiş derleme mantığı olarak ele alın.

Downgrade kurallarının, üretilen paket meta verilerinin, hedef çalışma zamanı denetimlerinin veya nextpdf/backport-builder sürüm otomasyonunun bakımını yaparken bu kılavuzu kullanın.

Mimari sınırlar

Katman	Sahibi	Sorumluluk	Buraya koymayın
Kaynak depoları	Ürün depoları	Geçerli PHP kaynağı ve testleri.	Üretilen downgrade düzenlemeleri.
Derleme betikleri	`nextpdf/backport-builder`	Kaynağı birleştirir, dönüşümleri çalıştırır, meta verileri yazar ve çıktıyı doğrular.	Çalışma zamanı uygulama mantığı.
Rector yapılandırması	`nextpdf/backport-builder`	Hedefe özgü downgrade ilkesi.	Testi olmayan hedefler arası varsayımlar.
Özel Rector kuralları	`nextpdf/backport-builder`	Projeye özgü söz dizimi dönüşümleri.	Geniş kapsamlı ve test kapsamı olmayan yeniden yazımlar.
Üretilen paketler	Derleme çıktısı	Eski çalışma zamanları için kurulabilir yapıtlar.	Elle yapılan gerçek-kaynak yamaları.

Derleme yaşam döngüsü

Aşama	Davranış	Geliştirici eylemi
Kaynak teslim alma	Sürüm iş akışı, kaynak depolarını hedef etikette teslim alır.	Kaynak referanslarını paketler arasında hizalı tutun.
Sözleşme doğrulaması	`ValidateBuildContract::run()` derleme varsayımlarını denetler.	Bir sözleşme başarısız olursa bunu sürümü engelleyen bir durum olarak ele alın.
Birleştirme	`MergeSources::run()` hedef paket ağacını bir araya getirir.	Rector’ı çalıştırmadan önce hedef kapsamını doğrulayın.
Dönüştürme	Rector yapılandırmaları ve özel kurallar, söz dizimini downgrade eder.	Her kural değişikliği için fixture testleri ekleyin.
Composer ayarlaması	`AdjustComposer` üretilen paket meta verilerini ve replace eşlemelerini yazar.	Paket adlarını, sürümlerini, lisanslarını ve kısıtlarını doğrulayın.
Çalışma zamanı doğrulaması	Üretilen çıktı, hedef PHP sürümlerinde söz dizimi açısından denetlenir ve test edilir.	Hedef çalışma zamanı başarısızlığını sürümü engelleyen bir durum olarak ele alın.
Sürüm	Arşivler bir sürüme eklenir.	Üretilen çıktıya gerçek-kaynak gibi yama uygulamayın.

Önerilen depo iş akışı

İş öğesi	Gerçek kaynak	Üretilen çıktı ilkesi
PHP özelliği kullanımı	Ana kaynak deposu.	Backport kuralları, özelliği uyarlar.
Bağımlılık kısıtları	Kaynak `composer.json` meta verileri ve ayarlama betiği.	Üretilen `composer.json` yeniden üretilebilir olmalıdır.
Söz dizimi downgrade’i	Rector yapılandırması ve özel kurallar.	Üretilen kaynak elle düzenlenmemelidir.
Çalışma zamanı desteği	Hedef dalı ve CI matrisi.	Derleme, hedef PHP üzerinde başarılı olmalıdır.
Sürüm notları	Belgeler ve sürüm otomasyonu.	Üretilen yapıtlar kaynak sürüme geri bağlantı içermelidir.

Özel Rector kuralı deseni

Her özel kuralın dar bir amacı, meta verileri ve fixture kapsamı olmalıdır.

Kural yöntemi	Amaç	Kalite gereksinimi
`getRuleDefinition()`	Rector araçları için dönüşümü belgeler.	Gerçek downgrade ile eşleşen bir before/after örneği ekleyin.
`getNodeTypes()`	Kuralın incelediği AST düğümlerini sınırlar.	Düğüm listesini olabildiğince küçük tutun.
`refactor()`	Dönüşümü uygular veya düğümü değiştirmeden döndürür.	İlgisiz düğümlere dokunmayın ve sonucu belirlenimci tutun.
Fixture testi	before/after çıktısını doğrular.	Geçerli en küçük girdiyi ve en az bir atlama durumunu kapsayın.

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

Derleme komutu deseni

Geliştirme ve sürüm adayı doğrulaması sırasında dry run’ları kullanın. Gerçek çıktıyı yalnızca kaynak referansları ve hedef dalı bilindiğinde yazın.

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

Üretilen paket doğrulamasını yalnızca modern derleme ana makinesinde değil, hedef çalışma zamanında da çalıştırın.

Genişletme noktaları

Genişletme noktası	Kullanım amacı	Kısıt
Rector yapılandırma dosyaları	Hedefe özgü downgrade ilkesi.	PHP 8.1 ve PHP 7.4 hatlarını ayrı tutun.
Özel Rector kuralları	Projeye özgü söz dizimi dönüşümleri.	Meta verileri ve fixture testleri olmalıdır.
Composer ayarlama betiği	Üretilen paket kimliği.	SemVer ile uyumlu sürümlemeyi korumalıdır.
Birleştirme betiği	Kaynak paket girdisini seçmek ve biçimlendirmek.	Kaynak köklerini ve çıktı köklerini günlüğe kaydetmelidir.
Derleme iş akışı	Sürüm düzenlemesi.	Üretilen çıktıyı hedef çalışma zamanında doğrulamalıdır.

Geliştirme iş akışı

Desteklenmeyen söz dizimini minimal bir fixture içinde yeniden üretin.
Özel bir Rector kuralı ekleyin veya güncelleyin.
Kural için before/after fixture’ları ekleyin.
Dry run derlemeyi çalıştırın.
Üretilen çıktıyı hedef PHP çalışma zamanında doğrulayın.
Gerektiğinde aynı mantıksal değişikliği her kalıcı hedef dalına uygulayın.
Sürüm yapıtlarını, kaynak etiketlerinden ve derleme betiklerinden yeniden üretilebilir tutun.

Başarısızlıkları ele alma

Başarısızlık	Nerede ele alınmalı	Önerilen yanıt
Eksik kaynak deposu	Sözleşme doğrulaması veya birleştirme aşaması.	Derlemeyi durdurun ve teslim alma girdilerini düzeltin.
Rector ayrıştırma başarısızlığı	Dönüştürme aşaması.	Bir fixture’a indirgeyin ve kuralı veya yapılandırmayı güncelleyin.
Üretilen `composer.json` uyumsuzluğu	Composer ayarlama aşaması.	Üretilen meta verileri değil, oluşturma betiğini düzeltin.
Hedef söz dizimi başarısızlığı	Çalışma zamanı doğrulaması.	Dönüşüm düzeltilene kadar sürümü engelleyin.
Pro kaynağı kullanılamıyor	Derleme yapılandırması.	Yalnızca amaçlanan hedef buysa genel yapıtı derleyin.

Güvenli varsayılanlar

Husus	Varsayılan	Ne zaman geçersiz kılınmalı
Üretilen çıktı	Salt okunur yapıt.	Bunu asla gerçek-kaynak haline getirmeyin.
Dal modeli	Ayrı kalıcı hedef dalları.	Değişiklikleri bağımsız pull request’ler aracılığıyla eşitlenmiş tutun.
Derleme ana makinesi	Modern PHP.	Sürüme hazır olup olmadığını yine de hedef çalışma zamanı doğrulaması belirler.
Özel kurallar	Küçük ve fixture destekli.	Açık before/after örnekleri olmayan geniş kapsamlı dönüşümlerden kaçının.
PHP 7.4 hattı	Açıkça desteklenmediği sürece yalnızca Core.	Hedef çalışma zamanı doğrulaması olmadan Pro çıktısını dahil etmeyin.

Test kontrol listesi

Rector kuralı meta verisi testleri, her özel kuralı örnekle doğrular.
Fixture testleri her dönüşüm için önceki ve sonraki kodu kapsar.
Dry run derleme, sürüm işlerinden önce çalıştırılır.
Hedef çalışma zamanı söz dizimi denetimleri ve paket testleri üretilen çıktı üzerinde çalışır.
Composer meta verisi testleri paket adını, sürümünü, kısıtlarını, replace eşlemesini ve lisansını doğrular.
Derleme günlükleri kaynak yollarını, hedef yolunu, hedef çalışma zamanını, dry-run durumunu ve Pro dahil etme durumunu içerir.