การรันตัวสร้าง backport ใน release pipeline

เครื่องมือนี้เป็นเครื่องมือบิลด์ ไม่ใช่ dependency ขณะรันไทม์ หน้านี้อธิบายวิธีดำเนินการ release pipeline ที่สร้าง backport โดย pipeline นี้รันใน continuous integration (CI) และไม่รันในแอปพลิเคชันปลายทาง

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

เส้นทางโปรดักชันใช้ workflow สองตัว 0-ci.yml ทำหน้าที่เป็นเกตสำหรับตรวจทุกการเปลี่ยนแปลงบน branch ถาวรแต่ละ branch เมื่อมีการปล่อยซอร์ส ระบบจะทริกเกอร์ build.yml เพื่อบิลด์และปล่อยดิสทริบิวชัน workflow ทั้งสองตัวตรวจสอบยืนยันเทียบกับ .github/workflows/ แล้ว

เกต CI

0-ci.yml รันเมื่อเกิดอีเวนต์ push และ pull request สำหรับ PHP74 และ PHP81 โดยรัน job สามรายการตามลำดับ:

1. PHPStan (Build Tools) — composer analyse สำหรับ rector/rules และ scripts ที่ระดับ 10
2. PHPUnit (Rector Rules) — composer test ซึ่งเป็นชุด fixture สำหรับกฎที่กำหนดเองทั้งสามกฎ
3. Build Dry Run — composer build:dry ซึ่งถูกเกตไว้หลัง job สองตัวแรก

อีเวนต์ที่เชื่อถือได้จะใช้ PHP runner แบบ self-hosted ส่วน pull request จาก fork และ Dependabot จะใช้ runner แบบ GitHub-hosted ที่จัดเตรียม PHP 8.5 ไว้ ข้อกำหนดนี้ตรวจสอบยืนยันเทียบกับ 0-ci.yml (นิพจน์ runs-on และสเตป setup-php แบบมีเงื่อนไข) โมเดลสอง branch จะเกตการเปลี่ยนแปลงที่กระทบทั้งสองเป้าหมายอย่างเป็นอิสระบน pull request ของแต่ละ branch

ไปป์ไลน์การปล่อย

build.yml เป็นการบิลด์สำหรับโปรดักชัน โดยรันเมื่อเกิดอีเวนต์ repository_dispatch ชนิด source-release หรือรันด้วยตนเองผ่าน workflow_dispatch โดยรับแท็กเป็นอินพุต pipeline ขับเคลื่อนด้วยแท็กเวอร์ชัน หมายเลขเวอร์ชันมีรูปแบบ MAJOR.MINOR.PATCH เหนือ public API ที่ประกาศไว้ (Semantic Versioning 2.0.0 §2)

เลน PHP 8.1

1. build-php81 — เช็กเอาต์เครื่องมือบิลด์ จัดเตรียม PHP 8.5 ติดตั้ง dependency สำหรับการบิลด์ โคลน repository ของซอร์สตามแท็กรีลีส รัน scripts/build.php สลับ runner ไปเป็น PHP 8.1 ตรวจไวยากรณ์ output/src บน PHP 8.1 จากนั้นติดตั้งแพ็กเกจที่สร้างขึ้นด้วย --no-dev แล้วอัปโหลดเอาต์พุตเป็น artifact
2. validate-php81 — ดาวน์โหลด artifact จากนั้นติดตั้งและทดสอบบนเมทริกซ์ของ PHP 8.1, 8.2, 8.3 และ 8.4
3. release-php81 — ดาวน์โหลด artifact แล้วคอมมิตและติดแท็กทรีที่สร้างขึ้น สร้างไฟล์ zip ที่ยกเว้น vendor/ และ .git/ แล้วเผยแพร่ GitHub release พร้อมแนบไฟล์ดังกล่าว

เลน PHP 7.4

1. build-php74 — เช็กเอาต์เครื่องมือบิลด์บน branch PHP74 จัดเตรียม PHP 8.5 โคลนเฉพาะ repository ของซอร์สหลักตามแท็ก รัน scripts/build.php --target=php74 สลับไปเป็น PHP 7.4 แล้วตรวจไวยากรณ์ของเอาต์พุตบน PHP 7.4
2. validate-php74 — ติดตั้งและทดสอบบนเมทริกซ์ของ PHP 7.4 และ 8.0
3. release-php74 — สร้างไฟล์ zip จากเอาต์พุตที่เป็นซอร์สหลักเท่านั้น แล้วแนบเป็นไฟล์ที่สองกับรีลีสเดียวกัน

โฟลว์นี้ตรวจสอบยืนยันเทียบกับนิยาม job และเมทริกซ์ใน build.yml แล้ว

ทั้งสองเลนใช้ GitHub release เดียวกัน เลน PHP 8.1 สร้างรีลีส และเลน PHP 7.4 แนบไฟล์ของตนเองไปยังแท็กเดียวกัน กลุ่ม concurrency ชื่อ backport-build ที่ตั้งค่า cancel-in-progress: false จะรันการบิลด์ทีละรายการ ดังนั้นการปล่อยซอร์สสองครั้งจึงไม่เกิด race

การดำเนินการ pipeline

การทริกเกอร์การบิลด์

โดยปกติการบิลด์จะเริ่มโดยอัตโนมัติเมื่อองค์กรเจ้าของซอร์สเผยแพร่รีลีส หากต้องการบิลด์แท็กที่ระบุด้วยตนเองอีกครั้ง ให้ dispatch build.yml พร้อมอินพุตเป็นแท็ก เช่น v2.0.0 โทเค็นสำหรับ dispatch คือ secrets.BACKPORT_TRIGGER_TOKEN และใช้อนุญาตการโคลน repository ของซอร์ส ข้อกำหนดนี้ตรวจสอบยืนยันเทียบกับ build.yml (workflow_dispatch.inputs.tag, GH_TOKEN)

การอ่านผลการบิลด์ที่ล้มเหลว

สคริปต์บิลด์จะหยุดที่สเตจแรกที่ล้มเหลว และพิมพ์ชื่อสเตจกับข้อผิดพลาด สเตจทั้งห้าได้แก่ merge, Rector, การสร้าง composer.json, การคัดลอก asset และการตรวจสอบ หากสเตปตรวจไวยากรณ์หลังการบิลด์ล้มเหลว แสดงว่า Rector สร้างเอาต์พุตที่รันไทม์เป้าหมายปฏิเสธ สเตปนั้นทำหน้าที่ปกป้องรีลีส จับคู่ความล้มเหลวกับสาเหตุได้ที่ /integrations/backport/troubleshooting/

สิ่งที่เผยแพร่

รีลีสประกอบด้วยไฟล์ดิสทริบิวชันแบบ zip แพ็กเกจถูกส่งมอบเป็นแท็กเวอร์ชัน ไม่ใช่ branch ผู้ใช้งานติดตั้ง nextpdf/backport (และ nextpdf/backport-pro หากต้องการ) จากช่องทางรีลีส ไฟล์ zip นี้ยกเว้น vendor/ และ .git/ ข้อกำหนดนี้ตรวจสอบยืนยันเทียบกับ build.yml (zip -r ... -x '*/vendor/*' '*/.git/*')

การกำหนดเวอร์ชันให้เอาต์พุต

ไฟล์ composer.json ที่สร้างขึ้นจะใช้เวอร์ชันที่ส่งผ่านบรรทัดคำสั่ง (--version หรือแท็ก dispatch หลังตัด v นำหน้าออก) แพ็กเกจ Pro จะปักหมุด nextpdf/backport ไว้ที่ caret constraint ของ major.minor ที่ตรงกัน ข้อกำหนดนี้ตรวจสอบยืนยันเทียบกับ scripts/adjust-composer.php (majorMinor(), generateProComposer()) ให้รักษาแท็กรีลีสของซอร์สและเวอร์ชันของ backport ให้สอดคล้องกัน เพื่อให้แมป replace คงความสอดคล้องอยู่เสมอ

ถัดไป

• /integrations/backport/security-and-operations/ — ขอบเขตความเชื่อถือของ pipeline และแนวทางด้าน supply chain
• /integrations/backport/troubleshooting/ — เอกสารอ้างอิงความล้มเหลวของแต่ละสเตจ