คู่มือนักพัฒนา Backport Builder

ภาพรวมโดยย่อ

Backport Builder เป็นโปรเจกต์ด้านวิศวกรรมการรีลีส ให้ถือว่าที่เก็บซอร์สเป็นอินพุต ทรีที่สร้างขึ้นเป็นเอาต์พุต และกฎ Rector แบบกำหนดเองเป็นลอจิกการบิลด์ที่มีการทดสอบกำกับ

ใช้คู่มือนี้เมื่อจำเป็นต้องดูแลรักษากฎการดาวน์เกรด เมตาดาทาของแพ็กเกจที่สร้างขึ้น การตรวจสอบรันไทม์เป้าหมาย หรือระบบอัตโนมัติสำหรับการรีลีสของ nextpdf/backport-builder

ขอบเขตของสถาปัตยกรรม

เลเยอร์	เจ้าของ	ความรับผิดชอบ	ไม่ควรใส่ไว้ที่นี่
ที่เก็บซอร์ส	ที่เก็บผลิตภัณฑ์	ซอร์ส PHP และการทดสอบที่เป็นต้นฉบับอ้างอิง	การแก้ไขดาวน์เกรดที่สร้างขึ้น
สคริปต์การบิลด์	nextpdf/backport-builder	ผสานซอร์ส รันการแปลง เขียนเมตาดาทา และตรวจสอบความถูกต้องของเอาต์พุต	ลอจิกของแอปพลิเคชันในรันไทม์
การกำหนดค่า Rector	nextpdf/backport-builder	นโยบายการดาวน์เกรดเฉพาะเป้าหมาย	ข้อสมมติข้ามเป้าหมายที่ไม่มีการทดสอบรองรับ
กฎ Rector แบบกำหนดเอง	nextpdf/backport-builder	การแปลงไวยากรณ์เฉพาะโปรเจกต์	การเขียนใหม่แบบกว้างโดยไม่มีการทดสอบรองรับ
แพ็กเกจที่สร้างขึ้น	เอาต์พุตของการบิลด์	อาร์ติแฟกต์ที่ติดตั้งได้สำหรับรันไทม์รุ่นเก่า	แพตช์ที่ทำด้วยตนเองจนกลายเป็นต้นฉบับอ้างอิง

วงจรชีวิตของการบิลด์

ขั้นตอน	พฤติกรรม	การดำเนินการของนักพัฒนา
การเช็กเอาต์ซอร์ส	เวิร์กโฟลว์การรีลีสจะเช็กเอาต์ที่เก็บซอร์สตามแท็กเป้าหมาย	รักษาให้การอ้างอิงซอร์สสอดคล้องกันในทุกแพ็กเกจ
การตรวจสอบความถูกต้องของสัญญา	ValidateBuildContract::run() จะตรวจสอบข้อสมมติของการบิลด์	ให้ถือว่าสัญญาที่ไม่ผ่านเป็นตัวขัดขวางการรีลีส
การผสาน	MergeSources::run() จะประกอบทรีแพ็กเกจเป้าหมาย	ตรวจสอบขอบเขตเป้าหมายก่อนรัน Rector
การแปลง	การกำหนดค่า Rector และกฎแบบกำหนดเองจะดาวน์เกรดไวยากรณ์	เพิ่มการทดสอบ fixture สำหรับการเปลี่ยนแปลงกฎทุกครั้ง
การปรับ Composer	AdjustComposer จะเขียนเมตาดาทาของแพ็กเกจที่สร้างขึ้นและแมป replace	ตรวจสอบความถูกต้องของชื่อแพ็กเกจ เวอร์ชัน ใบอนุญาต และข้อจำกัด
การตรวจสอบความถูกต้องของรันไทม์	เอาต์พุตที่สร้างขึ้นจะได้รับการตรวจสอบไวยากรณ์และทดสอบบน PHP เวอร์ชันเป้าหมาย	ให้ถือว่าความล้มเหลวในรันไทม์เป้าหมายเป็นสิ่งที่ขัดขวางการรีลีส
การรีลีส	แนบอาร์ไคฟ์เข้ากับการรีลีส	อย่าแพตช์เอาต์พุตที่สร้างขึ้นเพื่อให้เป็นต้นฉบับอ้างอิง

เวิร์กโฟลว์ที่แนะนำสำหรับที่เก็บ

งาน	ต้นฉบับอ้างอิง	นโยบายเอาต์พุตที่สร้างขึ้น
การใช้คุณสมบัติของ PHP	ที่เก็บซอร์สหลัก	กฎ backport จะปรับตามคุณสมบัตินั้น
ข้อจำกัดของ dependency	เมตาดาทาใน composer.json ของซอร์สและสคริปต์การปรับแต่ง	ไฟล์ composer.json ที่สร้างขึ้นต้องสามารถสร้างซ้ำได้
การดาวน์เกรดไวยากรณ์	การกำหนดค่า Rector และกฎแบบกำหนดเอง	ซอร์สที่สร้างขึ้นไม่ควรถูกแก้ไขด้วยตนเอง
การรองรับรันไทม์	สาขาเป้าหมายและเมทริกซ์ CI	การบิลด์ต้องผ่านบน PHP เป้าหมาย
บันทึกการรีลีส	เอกสารและระบบอัตโนมัติของการรีลีส	อาร์ติแฟกต์ที่สร้างขึ้นควรเชื่อมโยงกลับไปยังการรีลีสของซอร์ส

รูปแบบของกฎ Rector แบบกำหนดเอง

กฎแบบกำหนดเองแต่ละข้อควรมีวัตถุประสงค์ที่ชัดและจำกัด มีเมตาดาทา และมี fixture ครอบคลุม

เมธอดของกฎ	วัตถุประสงค์	ข้อกำหนดด้านคุณภาพ
getRuleDefinition()	จัดทำเอกสารการแปลงสำหรับเครื่องมือ Rector	ใส่ตัวอย่าง before/after ที่ตรงกับการดาวน์เกรดจริง
getNodeTypes()	จำกัดโหนด AST ที่กฎตรวจสอบ	รักษารายการโหนดให้เล็กที่สุดเท่าที่จะทำได้
refactor()	ใช้การแปลงหรือคืนค่าเดิมโดยไม่เปลี่ยนแปลง	ปล่อยโหนดที่ไม่เกี่ยวข้องไว้ตามเดิมและให้ผลลัพธ์ที่กำหนดแน่นอน
การทดสอบ fixture	ตรวจสอบเอาต์พุต before/after	ครอบคลุมอินพุตที่ถูกต้องขนาดเล็กที่สุดและกรณีที่ต้องข้ามอย่างน้อยหนึ่งกรณี

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

รูปแบบคำสั่งการบิลด์

ใช้การรันแบบ dry run ระหว่างการพัฒนาและเมื่อตรวจสอบความถูกต้องของ release candidate เขียนเอาต์พุตจริงเฉพาะเมื่อทราบการอ้างอิงซอร์สและสาขาเป้าหมายแล้ว

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

รันการตรวจสอบความถูกต้องของแพ็กเกจที่สร้างขึ้นบนรันไทม์เป้าหมาย ไม่ใช่เฉพาะบนโฮสต์การบิลด์รุ่นใหม่

จุดขยาย

จุดขยาย	ใช้สำหรับ	ข้อจำกัด
ไฟล์การกำหนดค่า Rector	นโยบายการดาวน์เกรดเฉพาะเป้าหมาย	แยกเลน PHP 8.1 และ PHP 7.4 ออกจากกัน
กฎ Rector แบบกำหนดเอง	การแปลงไวยากรณ์เฉพาะโปรเจกต์	ต้องมีเมตาดาทาและการทดสอบ fixture
สคริปต์การปรับ Composer	เอกลักษณ์ของแพ็กเกจที่สร้างขึ้น	ต้องรักษาการกำหนดเวอร์ชันที่สอดคล้องกับ SemVer
สคริปต์การผสาน	เลือกและกำหนดรูปแบบอินพุตแพ็กเกจซอร์ส	ต้องบันทึกล็อกของรูทซอร์สและรูทเอาต์พุต
เวิร์กโฟลว์การบิลด์	การจัดการการรีลีส	ต้องตรวจสอบความถูกต้องของเอาต์พุตที่สร้างขึ้นบนรันไทม์เป้าหมาย

เวิร์กโฟลว์การพัฒนา

1. จำลองไวยากรณ์ที่ไม่รองรับซ้ำใน fixture ที่เล็กที่สุด
2. เพิ่มหรืออัปเดตกฎ Rector แบบกำหนดเอง
3. เพิ่ม fixture before/after สำหรับกฎ
4. รัน dry build
5. ตรวจสอบความถูกต้องของเอาต์พุตที่สร้างขึ้นบนรันไทม์ PHP เป้าหมาย
6. นำการเปลี่ยนแปลงเชิงตรรกะเดียวกันไปใช้กับสาขาเป้าหมายถาวรแต่ละสาขาเมื่อจำเป็น
7. รักษาให้อาร์ติแฟกต์การรีลีสสามารถสร้างซ้ำได้จากแท็กของซอร์สและสคริปต์การบิลด์

การจัดการความล้มเหลว

ความล้มเหลว	ตำแหน่งที่ควรจัดการ	การตอบสนองที่แนะนำ
ไม่พบที่เก็บซอร์ส	ขั้นตอนการตรวจสอบความถูกต้องของสัญญาหรือการผสาน	หยุดการบิลด์และแก้ไขอินพุตของการเช็กเอาต์
การแยกวิเคราะห์ของ Rector ล้มเหลว	ขั้นตอนการแปลง	ย่อกรณีให้เป็น fixture และอัปเดตกฎหรือการกำหนดค่า
ไฟล์ composer.json ที่สร้างขึ้นไม่ตรงกัน	ขั้นตอนการปรับ Composer	แก้ไขสคริปต์การบิลด์ ไม่ใช่เมตาดาทาที่สร้างขึ้น
ไวยากรณ์เป้าหมายล้มเหลว	การตรวจสอบความถูกต้องของรันไทม์	ระงับการรีลีสจนกว่าการแปลงจะได้รับการแก้ไข
ซอร์ส Pro ไม่พร้อมใช้งาน	การกำหนดค่าการบิลด์	สร้างอาร์ติแฟกต์สาธารณะเฉพาะเมื่อนั่นเป็นเป้าหมายที่ตั้งใจไว้

ค่าเริ่มต้นที่ปลอดภัย

ประเด็น	ค่าเริ่มต้น	เมื่อใดควรแทนที่
เอาต์พุตที่สร้างขึ้น	อาร์ติแฟกต์แบบอ่านอย่างเดียว	ห้ามทำให้กลายเป็นต้นฉบับอ้างอิงเด็ดขาด
แบบจำลองสาขา	แยกสาขาเป้าหมายถาวรออกจากกัน	รักษาการเปลี่ยนแปลงให้ซิงโครไนซ์กันผ่าน pull request ที่เป็นอิสระต่อกัน
โฮสต์การบิลด์	PHP รุ่นใหม่	การตรวจสอบความถูกต้องของรันไทม์เป้าหมายยังคงเป็นตัวตัดสินความพร้อมในการรีลีส
กฎแบบกำหนดเอง	มีขนาดเล็กและมี fixture รองรับ	หลีกเลี่ยงการแปลงแบบกว้างโดยไม่มีตัวอย่าง before/after ที่ชัดเจน
เลน PHP 7.4	เฉพาะ Core เว้นแต่จะมีการรองรับอย่างชัดเจน	อย่ารวมเอาต์พุต Pro โดยไม่มีการตรวจสอบความถูกต้องของรันไทม์เป้าหมาย

รายการตรวจสอบการทดสอบ

• การทดสอบเมตาดาทาของกฎ Rector จะสร้างอินสแตนซ์ของกฎแบบกำหนดเองทุกข้อ
• การทดสอบ fixture ครอบคลุมโค้ด before/after สำหรับการแปลงแต่ละครั้ง
• รัน dry build ก่อนงานการรีลีส
• การตรวจสอบไวยากรณ์และการทดสอบแพ็กเกจสำหรับรันไทม์เป้าหมายจะรันบนเอาต์พุตที่สร้างขึ้น
• การทดสอบเมตาดาทาของ Composer จะยืนยันชื่อแพ็กเกจ เวอร์ชัน ข้อจำกัด แมป replace และใบอนุญาต
• ล็อกการบิลด์รวมพาธของซอร์ส พาธเป้าหมาย รันไทม์เป้าหมาย สถานะ dry-run และสถานะการรวม Pro