compare-builds

ビルドを比較する

クイックスタート

通常は、2 つのビルド識別子（ID、ダッシュボード URL、またはブランチ名）が渡されます。以下の手順に従ってください。

1. tuist build list --json を実行して、各ブランチのビルドを確認します。
2. ベースビルドとヘッドビルドの両方について、tuist build show <build-id> --json を実行します。
3. サブリソースの詳細を取得します。ターゲット（tuist build xcode target list <id> --json）、問題（tuist build xcode issue list <id> --json）、キャッシュタスク（tuist build xcode cache-task list <id> --json）を確認します。
4. 所要時間、ステータス、キャッシュヒット率、その他のメトリクスを比較します。
5. 退行、改善点、推奨事項をまとめます。

識別子が 1 つだけ指定された場合は、プロジェクトのデフォルトブランチをベースラインとして使用します。

ステップ 1：ビルドを特定する

base/head がビルド ID またはダッシュボード URL の場合

それぞれを直接取得します。

tuist build show <base-id> --json
tuist build show <head-id> --json

base/head がブランチ名の場合

各ブランチの最近のビルドを一覧表示し、最新のものを選びます。

tuist build list --git-branch <base-branch> --json --page-size 1
tuist build list --git-branch <head-branch> --json --page-size 1

その後、tuist build show <id> --json で詳細を取得します。

デフォルト

• base が指定されていない場合は、プロジェクトのデフォルトブランチ（通常は main）を使用します。
• head が指定されていない場合は、git rev-parse --abbrev-ref HEAD で現在の Git ブランチを検出します。

ステップ 2：サブリソースの詳細を取得する

tuist build show <id> --json で両方のビルドを取得した後、サブリソースを詳しく確認して比較します。

ターゲットを比較する

tuist build xcode target list <base-id> --json
tuist build xcode target list <head-id> --json

ステータスが変わったターゲット（成功から失敗など）や、所要時間が大幅に変わったターゲットを確認します。

問題を比較する

tuist build xcode issue list <base-id> --json
tuist build xcode issue list <head-id> --json

ヘッドビルドで新たに発生した警告やエラーを確認します。

キャッシュタスクを比較する

tuist build xcode cache-task list <base-id> --json
tuist build xcode cache-task list <head-id> --json

キャッシュミスまたはキャッシュヒットが発生した具体的なターゲットと、ビルド間でその状況が変わったかどうかを特定します。

ステップ 3：トップレベルのメトリクスを比較する

両方のビルドを取得した後、以下を比較します。

メトリクス	確認する内容
duration	head が base より 10% を超えて遅い場合は指摘します
status	base が成功し、head が失敗した場合は指摘します
cacheable_tasks_count	タスク数が変わったかを記録します
cacheable_task_local_hits_count	ローカルヒット数を比較します
cacheable_task_remote_hits_count	リモートヒット数を比較します
キャッシュヒット率	(local_hits + remote_hits) / cacheable_tasks_count * 100
category	一方が clean、もう一方が incremental かどうかを確認します（その場合、所要時間の比較はあまり意味がありません）
scheme / configuration	公平に比較できるよう、両方のビルドで同じスキームと構成が使われていることを確認します

キャッシュミスの差分を計算します：base_misses - head_misses。正の値は head のミスが少ない（改善）ことを示します。負の値は退行を示します。

ステップ 4：所要時間の退行を調査する

ヘッドビルドが大幅に遅い場合：

1. category が異なるか確認します（クリーンビルドとインクリメンタルビルドは直接比較できません）。
2. キャッシュヒット率が低下していないか確認します。低下している場合は、ビルド時間が長くなった理由を説明できる可能性があります。
3. 両方がインクリメンタルビルドで、キャッシュ率も同程度の場合、退行の原因はコンパイル時間にある可能性が高いです。

ステップ 5：キャッシュの変化を調査する

キャッシュ統計を比較します。

• ヒット率が低下：依存関係の変更、ビルド設定の変更、Xcode バージョンの更新などが考えられます。
• ヒット率が改善：キャッシュのウォームアップが適切になったか、ソースの変更が減ったことが原因と考えられます。
• タスク数が変化：新しいターゲットが追加または削除されています。

ステップ 6：ビルドのコンテキストを確認する

環境の詳細を比較します。

• xcode_version と macos_version：バージョンの違いは、ビルド時間やキャッシュの有効性に影響する可能性があります。
• is_ci：CI ビルドとローカルビルドでは、パフォーマンス特性が異なる場合があります。
• git_branch と git_commit_sha：ビルドが想定したコミットから作成されていることを確認します。

まとめの形式

以下を含めてまとめます。

1. 全体的な評価：ベースと比較して、改善、悪化、または中立。
2. 所要時間：絶対値と変化率。
3. キャッシュヒット率：ヒット率の変化とその説明。
4. ステータス：ステータスの変化（合格から失敗、またはその逆）。
5. 環境：比較可能性に影響する環境の違いを記載します。
6. 推奨事項：調査結果に基づく、実行可能な次のステップ。

例：

Build Comparison: base (abc123 on main) vs head (def456 on feature-x)

Duration: 45.2s -> 62.8s (+39%) -- REGRESSION
Cache hit rate: 85% -> 72% (-13%) -- 8 new cache misses
Status: success -> success

Root cause: Cache hit rate dropped due to 8 targets with invalidated caches.
The dependency hash changed for FeatureModule, cascading to 7 downstream targets.

Recommendations:
- Investigate why FeatureModule's cache was invalidated
- Consider splitting large targets to reduce cascade impact

完了チェックリスト

• ベースとヘッドの両方のビルドを解決しました
• サブリソースの詳細（ターゲット、イシュー、キャッシュタスク）を取得しました
• 期間、キャッシュ、ステータスの指標を比較しました
• リグレッションの根本原因を特定しました
• 実行可能な推奨事項を提示しました