create-pr

create-pr

概要

このガイドでは、warp リポジトリでプルリクエストを作成する際のベストプラクティスについて説明します。master のマージ、変更の効率的な検証、Linear タスクへのリンク、適切なテストカバレッジの確保、効果的なレビューのための PR の構成を取り上げます。

関連スキル

• write-pr-description - PR 本文の作成：テンプレートの各セクション、文章、レビュアー向けの案内
• fix-errors - PR を作成する前に、対象を絞ったコンパイル、テスト、lint、フォーマットの失敗を修正する
• warp-integration-test - ユーザーに見えるフロー、リグレッション、P0 ユースケースの統合テストカバレッジを追加または更新する
• add-feature-flag - フィーチャーフラグで変更を制御する

PR 作成前のチェックリスト

1. feature ブランチに master をマージする

レビューを開始する前に、必ず feature ブランチに master をマージしてください。

git fetch origin
git merge origin/master

PR を作成する前に、ローカルでマージコンフリクトを解決してください。

2. 変更をレビューする

PR を作成する前に、提出する変更内容を確認してください。

# View commits in your branch (comparing against base branch)
git --no-pager log <base-branch>..HEAD --oneline

# View file statistics for changes
git --no-pager diff <base-branch>...HEAD --stat

# View full diff
git --no-pager diff <base-branch>...HEAD

これは、次の作業に役立ちます。

• 意図した変更がすべて含まれていることを確認する
• レビュー前に意図しない変更を見つける
• 正確な PR の説明を書く
• 正しいベースブランチと比較していることを確認する
• テスト： 必要に応じてテストを追加します。バグ修正にはリグレッションテスト、アルゴリズムコードにはユニットテスト、UI コンポーネントにはレイアウトテスト、P0 ユースケースには統合テストを含めます。詳しくは、以下の「テスト要件」を参照してください。

3. 実装エージェントによる検証を尊重する

PR の作成は検証の区切りではありません。実装ワークフローですでにテスト、lint チェック、最終的なフォーマットが完了しており、候補に変更がない場合は、再実行しないでください。

master のマージまたは PR の準備によってソース、テスト、マニフェスト、生成コード、設定が変更された場合は、次の順序で新しい候補を検証します。

1. 関連するテストを実行し、合格するまでコードを修正します。
2. 該当する Clippy やその他の lint、型チェック、ビルドチェックを実行し、指摘事項を修正します。修正によって動作が実質的に変わる場合に限り、影響を受けるテストに戻ります。
3. ほかのコード変更がすべて完了した後に、./script/format を一度だけ実行します。

フォーマット後にテストや lint を再実行しないでください。また、ユーザー、タスク、承認済みの仕様で明示的に求められていない限り、./script/presubmit を実行しないでください。対象を絞ったローカル検証の範囲外にある一般的でない失敗は、CI が担当します。ドキュメントのみの変更では、Rust のテスト、Clippy、フォーマットは不要です。

4. Linear タスクにリンクする

可能な場合は、PR を Linear タスクに関連付けてください。対応するイシューを見つけるには、Linear MCP ツール（利用可能な場合）を使用します。

ブランチの命名規則： リモートブランチには、名前をプレフィックスとして付けてください（例：zheng/feature、alice/fix-bug）。

PR を Linear にリンクする方法： 自動でリンクされるように、PR を作成する前にタイトルにイシュー ID を含めてください（例：[WARP-1234] 新機能を追加）。

5. PR を作成する

PR を作成する際は、.github/pull_request_template.md のテンプレートを使用してください。

適切な場合は、PR テンプレートの末尾に記載されている形式で変更履歴の項目を追加してください。例：

• 機能：「現在のディレクトリ内のファイルを横断するグローバル検索。CMD-F/CTRL-SHIFT-F で開きます。」
• 改善：「行／列へのジャンプ時に水平オートスクロールを追加しました。」
• バグ修正：「エージェントがコマンドを実行すると、セッションビューアーの入力がクリアされる問題を修正しました。」

CLI ワークフロー：

• 現在のブランチに PR が存在するか確認する：

  gh pr view --json number,url
  

  PR が存在する場合は終了コード 0、存在しない場合は 1 です。

• 新しい PR を作成する：

  # With title and body
  gh pr create --title "Title" --body "Description" --draft
  
  # Auto-fill from commits
  gh pr create --fill --draft
  
  # Use PR template file
  gh pr create --body-file .github/pull_request_template.md --title "Title" --draft
  

  主なフラグ：--draft / -d、--fill / -f、--body-file / -F、--web / -w

• 既存の PR を更新する：

  gh pr edit --title "New title" --body "New body"
  gh pr edit --add-reviewer username --add-label bug
  

• PR をレビュー可能な状態にする：

  gh pr ready
  

6. 共同作成者の表記を含める

変更をコミットする際は、コミットメッセージの末尾にトレーラーとして表記を追加してください。PR の説明には記載しないでください。また、コミットに Warp/Oz の共同作成者トレーラーがすでにある場合、2 つ目を追加しないでください。

Co-Authored-By: Warp Agent <[email protected]>

テスト要件

バグ修正にはリグレッションテストが必要です

すべてのバグ修正には、リグレッションテストを添えてください。 これは、一度壊れた箇所が再び壊れることを防ぐのに役立ちます。

テストは次の条件を満たす必要があります。

• 元のバグを再現する (修正前なら失敗する)
• 修正を適用すると成功する
• どのバグを防いでいるのかがわかる明確な名前を付ける

アルゴリズム的なコードにはユニットテストが必要です

自明ではないロジックを含むコードには、機能を検証するユニットテストが必要です。

ユニットテストが必要なものの例:

• カスタムデータ構造 (例: SumTree)
• 特定のクエリに対して期待される結果を返すべき検索関連 API
• UI フレームワークにおけるコアレイアウトコード
• あらゆるアルゴリズム的または計算的なロジック

不要なもの:

• 十分に単純な関数
• 自明なゲッター/セッター

ユニットテストの書き方については、リポジトリのローカルなテスト規約に従ってください。

UI コンポーネントにはレイアウト検証テストが必要です

すべての UI コンポーネント (View の実装) には、パニックせずにレイアウトできることを検証するシンプルなユニットテストを用意してください。

これは、レンダリングの「安全性」(「正確性」ではありませんが) に対して高レベルのカバレッジを提供します。

#[test]
fn test_component_can_layout() {
    use warpui::App;
    use warp::test_util::{terminal::initialize_app_for_terminal_view, add_window_with_terminal};
    
    App::test((), |mut app| async move {
        initialize_app_for_terminal_view(&mut app);
        let term = add_window_with_terminal(&mut app, None);
        
        // Render the component - should not panic
        term.update(&mut app, |view, ctx| {
            // Create and layout your component
        });
    })
}

統合テストのカバレッジをスキップする前に確認してください

PR がユーザーから見えるフローを変更する場合、エンドツーエンドのリグレッションを修正する場合、その他統合テストのカバレッジがあると明らかに有益と思われる場合は、PR を作成または更新する前に ask_user_question ツールを使用して、その作業の一環として統合テストを追加したいかどうかをユーザーに確認してください。

次のような直接的な選択肢を推奨します。

• はい、PR を作成する前に統合テストを追加してください
• いいえ、統合テストなしで続行してください

ユーザーが追加を選んだ場合は、warp-integration-test スキルを使用してください。

P0 ユースケースには統合テストが必要です

すべての「P0 ユースケース」には、対象の動作/フローをカバーする統合テストが必要です。

「P0 ユースケース」は次のように定義されます: アプリケーションの動作のうち、壊れた場合に定例外リリースが必要となるもの。

統合テストは次の条件を満たす必要があります。

• ユーザーから見えるフロー全体を実行する
• エンドツーエンドの機能を検証する
• integration/ ディレクトリに配置する

実装の詳細、テスト登録の手順、検証ワークフローについては、warp-integration-test スキルを使用してください。

PR 説明文のガイドライン

本文自体には write-pr-description スキルを使用してください。このスキルは、 リポジトリのテンプレートへの準拠、文章のベースライン、レビュアー向けに 読む順序や注目すべき領域をいつ追加するかをカバーしています。

PR を開いた後

1. CI チェックを監視する - すべての自動チェックが成功することを確認します
2. レビューコメントに応答する - フィードバックに迅速に対応します
3. PR を最新の状態に保つ - コンフリクトが発生した場合は master をマージします
4. 変更された候補を検証する - レビューのフィードバックによるコード変更の後は、影響を受けるテストを実行し、次に lint チェック、そして ./script/format を一度実行します。PR のメタデータや変更されていない候補に対して検証を繰り返さないでください。

ベストプラクティス

• PR を焦点を絞ったものにする - 可能であれば 1 つの PR につき 1 つの論理的な変更にする
• 明確なコミットメッセージを書く - 何をしたかだけでなく、なぜそうしたのかを説明する
• まず自己レビューを行う - レビューを依頼する前に自分の差分をレビューする
• テストを更新する - テストカバレッジが変更内容を反映していることを確認する
• 破壊的な変更を文書化する - API の変更や破壊的な変更があれば明記する
• フィーチャーフラグを使用する - 適切な場合はリスクの高い変更をフィーチャーフラグの背後に置く (add-feature-flag スキルを参照)