Backport Builder 開発者ガイド

概要

Backport Builder はリリースエンジニアリング用のプロジェクトです。ソースリポジトリを入力、生成されたツリーを出力として扱い、カスタム Rector ルールをテスト済みのビルドロジックとして位置付けます。

ダウングレードルール、生成されたパッケージメタデータ、ターゲットランタイムのチェック、または nextpdf/backport-builder 周辺のリリース自動化を保守する際は、このガイドを参照してください。

アーキテクチャの境界

レイヤー	所有者	責務	ここに置かないもの
ソースリポジトリ	製品リポジトリ	正規の PHP ソースとテスト。	生成されたダウングレードへの編集。
ビルドスクリプト	`nextpdf/backport-builder`	ソースのマージ、変換の実行、メタデータの書き込み、出力の検証。	ランタイムのアプリケーションロジック。
Rector の設定	`nextpdf/backport-builder`	ターゲット固有のダウングレードポリシー。	テストのないターゲット横断の前提。
カスタム Rector ルール	`nextpdf/backport-builder`	プロジェクト固有の構文変換。	テストされていない広範な書き換え。
生成されたパッケージ	ビルド出力	古いランタイム向けのインストール可能な成果物。	信頼できる情報源（source of truth）への手動パッチ。

ビルドのライフサイクル

ステージ	動作	開発者のアクション
ソースのチェックアウト	リリースワークフローによる、ソースリポジトリのターゲットタグでのチェックアウト。	パッケージ全体でのソース参照の整合性維持。
コントラクトの検証	`ValidateBuildContract::run()` による、ビルド前提条件のチェック。	コントラクト失敗のリリース停止条件としての扱い。
マージ	`MergeSources::run()` による、ターゲットパッケージツリーの組み立て。	Rector 実行前のターゲット範囲の確認。
変換	Rector の設定とカスタムルールによる構文のダウングレード。	ルール変更ごとのフィクスチャテスト追加。
Composer の調整	`AdjustComposer` による、生成されたパッケージメタデータと replace マップの書き込み。	パッケージ名、バージョン、ライセンス、制約の検証。
ランタイムの検証	生成された出力に対する、ターゲットの PHP バージョンでの構文チェックとテスト。	ターゲットランタイム失敗のリリース停止条件としての扱い。
リリース	リリースへのアーカイブ添付。	生成された出力を信頼できる情報源（source of truth）としてパッチしないこと。

推奨されるリポジトリのワークフロー

作業項目	信頼できる情報源	生成された出力に関するポリシー
PHP 機能の使用	メインのソースリポジトリ。	バックポートルールによるその機能の適合。
依存関係の制約	ソースの `composer.json` メタデータと調整スクリプト。	生成された `composer.json` の再現可能性必須。
構文のダウングレード	Rector の設定とカスタムルール。	生成されたソースは手動で編集しないでください。
ランタイムのサポート	ターゲットブランチと CI マトリックス。	ターゲットの PHP でのビルド成功必須。
リリースノート	ドキュメントとリリースの自動化。	生成された成果物からソースリリースへたどれるリンク。

カスタム Rector ルールのパターン

カスタムルールはすべて、限定された目的、メタデータ、フィクスチャによるカバレッジを備えている必要があります。

ルールメソッド	目的	品質要件
`getRuleDefinition()`	Rector ツール向けの変換内容の記述。	実際のダウングレードと一致する before/after サンプルの同梱。
`getNodeTypes()`	ルールが検査する AST ノードの限定。	ノードリストをできるだけ小さく保つこと。
`refactor()`	変換の適用、または変更なしでの返却。	関連しないノードを変更せず、決定論的に保つこと。
フィクスチャテスト	before/after 出力の検証。	最小の有効な入力と、少なくとも 1 つのスキップケースのカバー。

<?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 の調整スクリプト	生成されたパッケージのアイデンティティ。	SemVer に沿ったバージョニングの維持必須。
マージスクリプト	ソースパッケージ入力の選択と整形。	ソースルートと出力ルートのログ記録必須。
ビルドワークフロー	リリースのオーケストレーション。	生成された出力のターゲットランタイムでの検証必須。

開発のワークフロー

サポートされていない構文を最小のフィクスチャで再現します。
カスタム Rector ルールを追加または更新します。
ルール用の before/after フィクスチャを追加します。
ドライビルドを実行します。
生成された出力をターゲットの PHP ランタイムで検証します。
必要に応じて、各恒久ターゲットブランチへ同じ論理的な変更を適用します。
リリース成果物を、ソースタグとビルドスクリプトから再現可能な状態に保ちます。

障害への対応

障害	対応すべき場所	推奨される対応
ソースリポジトリの欠落	コントラクト検証またはマージステージ。	ビルドの停止とチェックアウト入力の修正。
Rector の解析失敗	変換ステージ。	フィクスチャへの縮小と、ルールまたは設定の更新。
生成された `composer.json` の不一致	Composer の調整ステージ。	生成済みメタデータではなく、生成スクリプトの修正。
ターゲット構文の失敗	ランタイム検証。	変換が修正されるまでのリリースブロック。
Pro ソースが利用できない	ビルド設定。	意図したターゲットである場合に限る、パブリック成果物のビルド。

安全なデフォルト

考慮事項	デフォルト	オーバーライドするタイミング
生成された出力	読み取り専用の成果物。	信頼できる情報源（source of truth）に決してしないこと。
ブランチモデル	分離した恒久ターゲットブランチ。	独立したプルリクエストによる変更同期の維持。
ビルドホスト	最新の PHP。	リリース準備状況の判断は、引き続きターゲットランタイムの検証。
カスタムルール	小さく、フィクスチャに裏付けられたもの。	明示的な before/after 例がない広範な変換の回避。
PHP 7.4 のレーン	明示的にサポートされていない限り、コアのみ。	ターゲットランタイムの検証なしに Pro の出力を含めないこと。

テストのチェックリスト

Rector ルールのメタデータテストが、すべてのカスタムルールをインスタンス化します。
フィクスチャテストが、各変換について変換前と変換後のコードをカバーします。
ドライビルドがリリースジョブの前に実行されます。
ターゲットランタイムの構文チェックとパッケージテストを、生成された出力に対して実行します。
Composer メタデータテストが、パッケージ名、バージョン、制約、replace マップ、ライセンスをアサートします。
ビルドログに、ソースパス、ターゲットパス、ターゲットランタイム、ドライラン状態、Pro の取り込み状態を含めます。