create-pull-request

プルリクエストの作成

このスキルでは、プロジェクトの規約とベストプラクティスに従った、適切に構成された GitHub プルリクエストの作成方法を説明します。

前提条件の確認

進める前に、次の項目を確認してください。

1. gh CLI がインストールされているか確認する

gh --version

インストールされていない場合は、ユーザーに次のように伝えてください。

GitHub CLI（gh）が必要ですが、インストールされていません。次の方法でインストールしてください。

• macOS：brew install gh
• その他：https://cli.github.com/

2. GitHub に認証済みか確認する

gh auth status

認証されていない場合は、gh auth login を実行するようユーザーに案内してください。

3. 関連するスキルを確認する

PR を作成する前に、コードレビュー、CI、テストに関連するスキルが利用できるか確認してください。利用できる場合は、前提条件として先に実行する必要があります。

次の語句を含む説明のスキルを探してください。

• 「review」（例：コードレビュー、PR レビュー、web-design-guidelines）
• 「CI」または「ci-fix」（例：CI の失敗の修正）
• 「testing」または「test」（例：テストの実行、webapp-testing）

該当するスキルがある場合は、PR の作成に進む前に実行してください。例：

• ci-fix スキルがあり、CI が失敗している場合は、これを使って問題を診断し、修正します
• UI の変更に対して web-design-guidelines スキルがある場合は、これを使って変更をレビューします
• テスト用のスキルがある場合は、テストが通ることを確認するために実行します

これらの前提スキルを完了してから、PR の作成に進んでください。

4. 作業ディレクトリに未コミットの変更がないか確認する

git status

未コミットの変更がある場合は、次のどれにするかユーザーに尋ねてください。

• この PR の一部としてコミットする
• 一時的にスタッシュする
• 破棄する（慎重に行うこと）

既存の PR を確認する

コンテキストを収集する前に、現在のブランチにすでに PR が存在するか確認してください。

gh pr list --head $(git branch --show-current) --json number,title,url

すでに PR が存在する場合：

• 既存の PR の詳細（番号、タイトル、URL）を表示する
• 次のどれを行うかユーザーに尋ねる：
  • 既存の PR を表示する：gh pr view
  • 既存の PR を更新する（コミットを追加でプッシュすると、PR は自動的に更新されます）
  • 既存の PR をクローズして、新しい PR を作成する

このブランチに PR が存在しない場合にのみ、新しい PR の作成に進んでください。

コンテキストの収集

1. 現在のブランチを特定する

git branch --show-current

main または master ブランチではないことを確認してください。該当する場合は、フィーチャーブランチを作成するか、そこに切り替えるようユーザーに尋ねてください。

2. ベースブランチを見つける

git remote show origin | grep "HEAD branch"

通常は main または master です。

3. この PR に関連する最近のコミットを分析する

git log origin/main..HEAD --oneline --no-decorate

これらのコミットを確認して、次の点を把握してください。

• どのような変更が加えられるか
• PR の範囲（単一の機能／修正か、複数の変更か）
• コミットをスカッシュするか、再構成する必要があるか

4. 差分を確認する

git diff origin/main..HEAD --stat

これにより、変更されたファイルが表示され、変更の種類を特定しやすくなります。

情報の収集

利用可能なコンテキスト（コミットメッセージ、ブランチ名、変更されたファイル）から、次の情報を収集してください。

抽出する情報

1. 関連する Issue 番号：次の項目で #123、fixes #123、closes #123 のようなパターンを探します。

   • コミットメッセージ
   • ブランチ名（例：fix/issue-123、feature/123-new-login）
   • 見つかった場合は、PR のタイトルや説明に含めます
   • 見つからない場合は、含めずに進めます

2. 説明：どのような問題を解決するのか、なぜこれらの変更が行われたのか。

   • コミットメッセージと差分から推測します
   • 加えられた変更を説明します

3. 変更の種類：バグ修正、新機能、破壊的変更、リファクタリング、外観上の変更、ドキュメント、ワークフローのいずれか。

   • コミットメッセージと変更されたファイルから判断します

4. テスト手順：どのようにテストしたか、何が壊れる可能性があるか。

   • テストファイルが変更されている場合は、そのファイルに言及します
   • 変更内容から明らかな場合は、テスト方法を説明します

説明的な PR タイトルの作成

PR のタイトルは、説明的で内容が伝わるものにしてください。次のような一般的なタイトルは避けてください。

• 「initial commit」
• 「fix」
• 「update」
• 「changes」

代わりに、変更内容を明確に要約するタイトルを作成してください。次の方法を検討してください。

1. Conventional Commits 形式

以下を分析して、プロジェクトが Conventional Commits を使用しているか確認します。

• コミットメッセージに feat:、fix:、docs:、refactor:、test:、chore: などのパターンがあるか
• ブランチ名に feat/、fix/、docs/ などの接頭辞があるか

Conventional Commits が使われている場合は、PR タイトルに適切な接頭辞を使用します。

• feat: Add user authentication with OAuth
• fix: Resolve memory leak in data processing
• docs: Update API documentation for v2 endpoints
• refactor: Simplify error handling logic
• test: Add integration tests for payment flow
• chore: Update dependencies to latest versions

課題番号が見つかった場合は含めます。

• feat: Add user authentication with OAuth (#123)
• fix(auth): Resolve memory leak in data processing (fixes #456)

2. 内容を明確に表す要約

Conventional Commits を使用していない場合は、明確で行動指向のタイトルを作成します。

• 良い例：「検索結果にページネーションを追加」
• 悪い例：「initial commit」
• 良い例：「認証フローの競合状態を修正」
• 悪い例：「fix bug」

課題番号が見つかった場合は含めます。

• 「検索結果にページネーションを追加 (#123)」
• 「認証フローの競合状態を修正 (fixes #456)」

3. タイトルの生成方法

1. 最も重要なコミットメッセージ（多くの場合、最初または最後のもの）を確認します
2. 差分から主な変更点（新機能、バグ修正など）を特定します
3. 関連付けられている場合は、課題のタイトルを抽出します
4. これらから適切なタイトルを作成できない場合は、変更されたファイルとその目的からタイトルを考案します
5. コミットまたはブランチ名に課題番号がある場合は、タイトルに追加します

Git のベストプラクティス

PR を作成する前に、以下のベストプラクティスを検討します。

コミットの整理

1. アトミックコミット：各コミットは、1 つの論理的な変更を表す必要があります
2. 明確なコミットメッセージ：可能であれば Conventional Commits 形式に従います
3. マージコミットを作らない：履歴を整理された状態に保つため、マージよりリベースを優先します

ブランチ管理

1. 最新の main にリベースする（必要な場合）：

   git fetch origin
   git rebase origin/main
   

2. 適切にスカッシュする：小さな「WIP」コミットが多数ある場合は、対話型リベースを検討します。

   git rebase -i origin/main
   

   コミットが整理されておらず、ユーザーがリベースに慣れている場合にのみ、これを提案してください。

変更をプッシュする

すべてのコミットがプッシュされていることを確認します。

git push origin HEAD

ブランチをリベースした場合、次のコマンドが必要になることがあります。

git push origin HEAD --force-with-lease

プルリクエストを作成する

重要：.github/pull_request_template.md が存在する場合は、内容を確認して使用してください。PR 本文の形式はテンプレートの構成に合わせます。

テンプレートに記入する際は、以下の点に注意してください。

• コンテキストから課題番号が見つかった場合は含めます（例：Fixes #123、Closes #456）
• テンプレートがない場合は、以下を含む明確な説明を作成します。
  • 変更の概要
  • 関連する課題（見つかった場合）
  • 実施したテスト
  • 破壊的変更や特筆すべき影響
• コミットとコンテキストから得られた関連情報を使って、すべてのセクションに記入します
• テンプレートに「変更の種類」のチェックボックスがある場合は、適切なものにチェックを入れます
• 該当するチェックリスト項目をすべて完了します

ドラフト PR の判断

以下に基づいて、ドラフト PR と通常の PR のどちらを作成するか判断します。

次の場合は --draft フラグを使用します。

• 変更が未完成または作業中だが、早期にフィードバックを得たい
• テストが現在失敗しており、デバッグの支援が必要
• アーキテクチャ上の判断で行き詰まっており、助言が必要
• 後で作業を続けるための目印として PR を作成する
• CI チェックを実行したいが、正式なレビューを受ける準備ができていない

次の場合は通常の PR（--draft なし）を使用します。

• すべてのテストが成功し、コードがレビュー可能な状態
• 変更が完了しており、アプローチに確信がある
• PR のレビューとマージを早期に進めたい

gh CLI で PR を作成する

通常の PR の場合：

gh pr create --title "PR_TITLE" --body "PR_BODY" --base main

ドラフト PR の場合：

gh pr create --title "PR_TITLE" --body "PR_BODY" --base main --draft

作成後

PR を作成した後：

1. 確認のため、ブラウザーで PR を開く

作成が正しく完了したことを確認するため、すぐにブラウザーで PR を開きます。

gh pr view --web

これにより、次の点を確認できます。

• PR のタイトルと説明が正しく表示されること
• すべてのリンク（Issue への参照など）が機能すること
• 差分が想定どおりであること
• CI のステータスがすぐに確認できること

2. CI チェックについて知らせる

テストとリンティングは自動的に実行されます。チェックが成功するよう、状況を確認してください。

3. 必要に応じて次の手順を提案する

• 必要に応じてレビュアーを追加します：gh pr edit --add-reviewer USERNAME
• ラベルを追加します：gh pr edit --add-label "bug"

エラー処理

よくある問題

1. main より先に進んでいるコミットがない：ブランチに提出する変更がありません

   • 別のブランチで作業するつもりだったか、ユーザーに確認します

2. ブランチがプッシュされていない：リモートにブランチがありません

   • まずブランチをプッシュします：git push -u origin HEAD

3. PR がすでに存在する：このブランチの PR はすでに存在します

   • 既存の PR を表示します：gh pr view
   • 既存の PR を更新するか、ユーザーに確認します

4. マージコンフリクト：ブランチがベースブランチと競合しています

   • コンフリクトの解決またはリベースの手順を案内します

最終確認チェックリスト

最終確定する前に、以下を確認してください。

• gh CLI がインストールされ、認証済みである
• 関連するレビュー／CI／テストのスキルが呼び出されている
• このブランチに既存の PR がない
• 作業ディレクトリがクリーンである
• すべてのコミットがプッシュされている
• ブランチがベースブランチの最新状態に追従している
• PR のタイトルが具体的で、内容を適切に表している（汎用的なものではない）
• プロジェクトで採用している場合、PR のタイトルが Conventional Commits 形式になっている
• コンテキストに Issue 番号がある場合、タイトルまたは説明に含まれている
• PR の説明がテンプレートに沿っている（テンプレートがある場合）
• 適切な変更の種類が選択されている
• ドラフトか通常の PR かが正しく選択されている
• 確認のため、ブラウザーで PR が開かれている