Hướng dẫn cho nhà phát triển Backport Builder

Tổng quan nhanh

Backport Builder là một dự án kỹ thuật phát hành (release engineering). Hãy coi các kho nguồn là đầu vào, cây thư mục được tạo là đầu ra, và các quy tắc Rector tùy chỉnh là logic build đã qua kiểm thử.

Hãy dùng hướng dẫn này khi bạn duy trì các quy tắc hạ cấp (downgrade), siêu dữ liệu gói được tạo, kiểm tra runtime đích hoặc tự động hóa phát hành cho nextpdf/backport-builder.

Ranh giới kiến trúc

Lớp	Sở hữu bởi	Trách nhiệm	Không đặt ở đây
Kho nguồn	Kho sản phẩm	Mã nguồn PHP và các bài kiểm thử đóng vai trò nguồn chính thức.	Các chỉnh sửa hạ cấp được tạo.
Script build	`nextpdf/backport-builder`	Hợp nhất nguồn, chạy các phép biến đổi, ghi siêu dữ liệu và xác thực đầu ra.	Logic ứng dụng tại runtime.
Cấu hình Rector	`nextpdf/backport-builder`	Chính sách hạ cấp cho từng đích.	Các giả định dùng chung giữa các đích mà không có kiểm thử.
Quy tắc Rector tùy chỉnh	`nextpdf/backport-builder`	Các phép biến đổi cú pháp riêng của dự án.	Các phép viết lại diện rộng chưa được kiểm thử.
Gói được tạo ra	Đầu ra của build	Các artifact có thể cài đặt cho runtime cũ hơn.	Các bản vá thủ công vào nguồn chính thức.

Vòng đời build

Giai đoạn	Hành vi	Hành động của nhà phát triển
Checkout nguồn	Quy trình phát hành checkout các kho nguồn tại tag đích.	Giữ các tham chiếu nguồn nhất quán giữa các gói.
Xác thực hợp đồng	`ValidateBuildContract::run()` kiểm tra các giả định của build.	Hãy coi hợp đồng không đạt là điều kiện chặn phát hành.
Hợp nhất	`MergeSources::run()` lắp ráp cây thư mục gói đích.	Xác minh phạm vi đích trước khi chạy Rector.
Biến đổi	Các cấu hình Rector và quy tắc tùy chỉnh hạ cấp cú pháp.	Thêm bài kiểm thử fixture cho mọi thay đổi quy tắc.
Điều chỉnh Composer	`AdjustComposer` ghi siêu dữ liệu gói được tạo và các bản đồ replace.	Xác thực tên gói, phiên bản, giấy phép và các ràng buộc.
Xác thực runtime	Đầu ra được tạo sẽ được kiểm tra cú pháp và kiểm thử trên các phiên bản PHP đích.	Hãy coi lỗi runtime đích là điều kiện chặn phát hành.
Phát hành	Các bản lưu trữ được đính kèm vào một bản phát hành.	Không vá đầu ra được tạo như thể đó là nguồn chính thức.

Quy trình kho được khuyến nghị

Hạng mục công việc	Nguồn chính thức	Chính sách đầu ra được tạo ra
Việc sử dụng tính năng PHP	Kho nguồn chính.	Các quy tắc backport điều chỉnh tính năng.
Các ràng buộc phụ thuộc	Siêu dữ liệu `composer.json` nguồn cùng với script điều chỉnh.	Tệp `composer.json` được tạo phải có thể tái tạo.
Hạ cấp cú pháp	Cấu hình Rector và các quy tắc tùy chỉnh.	Không nên chỉnh sửa thủ công mã nguồn được tạo.
Hỗ trợ runtime	Nhánh đích và ma trận CI.	Build phải đạt trên PHP đích.
Ghi chú phát hành	Tài liệu và tự động hóa phát hành.	Các artifact được tạo nên liên kết ngược về bản phát hành nguồn.

Mẫu quy tắc Rector tùy chỉnh

Mỗi quy tắc tùy chỉnh nên có mục đích hẹp, siêu dữ liệu và độ bao phủ fixture.

Phương thức quy tắc	Mục đích	Yêu cầu chất lượng
`getRuleDefinition()`	Ghi lại phép biến đổi cho công cụ Rector.	Bao gồm một mẫu before/after khớp với phép hạ cấp thực tế.
`getNodeTypes()`	Giới hạn các node AST mà quy tắc xem xét.	Giữ danh sách node ở mức nhỏ nhất có thể.
`refactor()`	Áp dụng phép biến đổi hoặc trả về không thay đổi.	Giữ nguyên các node không liên quan và bảo đảm tính tất định.
Bài kiểm thử fixture	Xác minh đầu ra before/after.	Bao phủ đầu vào hợp lệ nhỏ nhất và ít nhất một trường hợp bỏ qua.

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

Mẫu lệnh build

Hãy dùng dry run trong quá trình phát triển và khi xác thực ứng viên phát hành (release candidate). Chỉ ghi đầu ra thật khi đã biết rõ các tham chiếu nguồn và nhánh đích.

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

Hãy chạy xác thực gói được tạo trên runtime đích, không chỉ trên máy build hiện đại.

Các điểm mở rộng

Điểm mở rộng	Dùng cho	Ràng buộc
Các tệp cấu hình Rector	Chính sách hạ cấp cho từng đích.	Giữ làn PHP 8.1 và PHP 7.4 tách biệt.
Quy tắc Rector tùy chỉnh	Các phép biến đổi cú pháp riêng của dự án.	Phải có siêu dữ liệu và bài kiểm thử fixture.
Script điều chỉnh Composer	Danh tính gói được tạo.	Phải duy trì việc đánh phiên bản tuân theo SemVer.
Script hợp nhất	Chọn và định hình đầu vào gói nguồn.	Phải ghi log các thư mục gốc nguồn và thư mục gốc đầu ra.
Quy trình build	Điều phối phát hành.	Phải xác thực đầu ra được tạo trên runtime đích.

Quy trình phát triển

Tái tạo cú pháp không được hỗ trợ trong một fixture tối thiểu.
Thêm hoặc cập nhật một quy tắc Rector tùy chỉnh.
Thêm các fixture before/after cho quy tắc.
Chạy bản build dry.
Xác thực đầu ra được tạo trên runtime PHP đích.
Áp dụng cùng một thay đổi logic cho mỗi nhánh đích cố định khi cần.
Giữ các artifact phát hành có thể tái tạo từ các tag nguồn và script build.

Xử lý lỗi

Lỗi	Nơi cần xử lý	Phản hồi được khuyến nghị
Thiếu kho nguồn	Giai đoạn xác thực hợp đồng hoặc hợp nhất.	Dừng build và sửa các đầu vào checkout.
Lỗi phân tích cú pháp của Rector	Giai đoạn biến đổi.	Thu nhỏ thành một fixture và cập nhật quy tắc hoặc cấu hình.
Tệp `composer.json` được tạo không khớp	Giai đoạn điều chỉnh Composer.	Sửa script tạo, không sửa siêu dữ liệu được tạo.
Lỗi cú pháp đích	Xác thực runtime.	Chặn phát hành cho đến khi phép biến đổi được sửa.
Nguồn Pro không khả dụng	Cấu hình build.	Chỉ build artifact công khai khi đó là đích dự kiến.

Giá trị mặc định an toàn

Vấn đề cần lưu tâm	Mặc định	Khi nào nên ghi đè
Đầu ra được tạo	Artifact chỉ đọc.	Không bao giờ biến nó thành nguồn chính thức.
Mô hình nhánh	Các nhánh đích cố định, tách biệt.	Giữ các thay đổi được đồng bộ thông qua các pull request độc lập.
Máy build	PHP hiện đại.	Việc xác thực runtime đích vẫn quyết định mức độ sẵn sàng phát hành.
Quy tắc tùy chỉnh	Nhỏ và được hỗ trợ bằng fixture.	Tránh các phép biến đổi diện rộng mà không có ví dụ before/after rõ ràng.
Làn PHP 7.4	Chỉ Core trừ khi được hỗ trợ rõ ràng.	Không bao gồm đầu ra Pro nếu chưa xác thực runtime đích.

Danh mục kiểm thử

Các bài kiểm thử siêu dữ liệu quy tắc Rector khởi tạo mọi quy tắc tùy chỉnh.
Các bài kiểm thử fixture bao phủ mã trước và sau cho mỗi phép biến đổi.
Bản build dry chạy trước các job phát hành.
Các kiểm tra cú pháp runtime đích và bài kiểm thử gói chạy trên đầu ra được tạo.
Các bài kiểm thử siêu dữ liệu Composer xác nhận tên gói, phiên bản, các ràng buộc, bản đồ replace và giấy phép.
Log build bao gồm đường dẫn nguồn, đường dẫn đích, runtime đích, trạng thái dry-run và trạng thái bao gồm Pro.