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 구성과 사용자 정의 규칙이 구문을 다운그레이드합니다.	모든 규칙 변경에 대해 픽스처 테스트를 추가하십시오.
Composer 조정	`AdjustComposer`에서 생성된 패키지 메타데이터와 교체 맵을 작성합니다.	패키지 이름, 버전, 라이선스, 제약 조건을 검증하십시오.
런타임 검증	생성된 출력은 대상 PHP 버전에서 구문 검사를 거치고 테스트됩니다.	대상 런타임 실패는 릴리스를 차단하는 것으로 취급하십시오.
릴리스	아카이브가 릴리스에 첨부됩니다.	생성된 출력을 신뢰 소스로 삼아 패치하지 마십시오.

권장 저장소 워크플로

작업 항목	신뢰 소스	생성된 출력 정책
PHP 기능 사용	기본 소스 저장소입니다.	Backport 규칙이 해당 기능을 맞게 조정합니다.
종속성 제약 조건	소스 `composer.json` 메타데이터와 조정 스크립트입니다.	생성된 `composer.json`은(는) 재현 가능해야 합니다.
구문 다운그레이드	Rector 구성과 사용자 정의 규칙입니다.	생성된 소스는 수동으로 편집하면 안 됩니다.
런타임 지원	대상 브랜치와 CI 매트릭스입니다.	빌드는 대상 PHP에서 통과해야 합니다.
릴리스 노트	문서와 릴리스 자동화입니다.	생성된 아티팩트는 소스 릴리스에 다시 연결되어야 합니다.

사용자 정의 Rector 규칙 패턴

모든 사용자 정의 규칙은 좁은 목적, 메타데이터, 픽스처 커버리지를 갖추어야 합니다.

규칙 메서드	목적	품질 요구 사항
`getRuleDefinition()`	Rector 도구를 위해 변환을 문서화합니다.	실제 다운그레이드와 일치하는 before/after 샘플을 포함하십시오.
`getNodeTypes()`	규칙이 검사하는 AST 노드를 제한합니다.	노드 목록을 가능한 한 작게 유지하십시오.
`refactor()`	변환을 적용하거나 변경하지 않고 반환합니다.	관련 없는 노드는 변경하지 말고, 결정적으로 동작하도록 유지하십시오.
픽스처 테스트	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);
    }
}

빌드 명령 패턴

개발 중이거나 릴리스 후보를 검증할 때는 드라이런을 사용하십시오. 소스 참조와 대상 브랜치가 확정된 경우에만 실제 출력을 사용하십시오.

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 규칙	프로젝트별 구문 변환입니다.	메타데이터와 픽스처 테스트를 갖추어야 합니다.
Composer 조정 스크립트	생성된 패키지 ID입니다.	SemVer에 맞춘 버전 관리를 유지해야 합니다.
병합 스크립트	소스 패키지 입력을 선택하고 구성합니다.	소스 루트와 출력 루트를 로깅해야 합니다.
빌드 워크플로	릴리스 오케스트레이션입니다.	대상 런타임에서 생성된 출력을 검증해야 합니다.

개발 워크플로

지원되지 않는 구문을 최소 픽스처로 재현하십시오.
사용자 정의 Rector 규칙을 추가하거나 업데이트하십시오.
규칙에 대한 before/after 픽스처를 추가하십시오.
드라이런 빌드를 실행하십시오.
대상 PHP 런타임에서 생성된 출력을 검증하십시오.
필요한 경우 각 영구 대상 브랜치에 동일한 논리적 변경을 적용하십시오.
릴리스 아티팩트가 소스 태그와 빌드 스크립트에서 재현 가능하도록 유지하십시오.

실패 처리

실패	처리되어야 할 위치	권장 대응
소스 저장소 누락	계약 검증 또는 병합 단계입니다.	빌드를 중지하고 체크아웃 입력을 수정하십시오.
Rector 파싱 실패	변환 단계입니다.	픽스처로 축소하고 규칙 또는 구성을 업데이트하십시오.
생성된 `composer.json` 불일치	Composer 조정 단계입니다.	생성된 메타데이터가 아니라 생성 스크립트를 수정하십시오.
대상 구문 실패	런타임 검증입니다.	변환이 수정될 때까지 릴리스를 차단하십시오.
Pro 소스 사용 불가	빌드 구성입니다.	공개 아티팩트가 의도된 대상인 경우에만 빌드하십시오.

안전한 기본값

관심사	기본값	재정의해야 하는 경우
생성된 출력	읽기 전용 아티팩트입니다.	이를 신뢰 소스로 만들지 마십시오.
브랜치 모델	분리된 영구 대상 브랜치입니다.	독립적인 풀 리퀘스트로 변경 사항을 동기화된 상태로 유지하십시오.
빌드 호스트	최신 PHP입니다.	대상 런타임 검증이 여전히 릴리스 준비 상태를 결정합니다.
사용자 정의 규칙	작고 픽스처로 뒷받침됩니다.	명시적인 before/after 예제 없이 광범위한 변환을 피하십시오.
PHP 7.4 레인	명시적으로 지원되지 않는 한 코어 전용입니다.	대상 런타임 검증 없이 Pro 출력을 포함하지 마십시오.

테스트 체크리스트

Rector 규칙 메타데이터 테스트는 모든 사용자 정의 규칙을 인스턴스화합니다.
픽스처 테스트는 각 변환에 대해 변경 전후 코드를 다룹니다.
드라이 빌드는 릴리스 작업 전에 실행됩니다.
생성된 출력에 대해 대상 런타임 구문 검사와 패키지 테스트를 실행합니다.
Composer 메타데이터 테스트는 패키지 이름, 버전, 제약 조건, 교체 맵, 라이선스를 어설션합니다.
빌드 로그에는 소스 경로, 대상 경로, 대상 런타임, 드라이런 상태, Pro 포함 상태가 기록됩니다.