write-pr-description

PR の説明を作成する

現在の変更内容からタイトルと本文を作成します。リポジトリの PR テンプレート、または デフォルトのテンプレートを使用します。公開前にテキストを提示してください。

デフォルトは下書きのみで、gh もネットワークアクセスも必要ありません。ユーザーが PR を開く、作成する、または提出するよう求めた場合は、作成モードを適用します。テキストの承認後に必要なプッシュも含まれます。

ステップ 1 — 未コミットのタスクファイルを確認する

未追跡ファイルも含めて、git status --short を確認します。タスクに属するファイルを特定し、無関係な変更には触れず、簡潔に名前を挙げます。対象範囲が不明な場合は質問してください。

作成モードでタスクファイルが未コミットの場合は、そのパスを提示して次のように尋ねます。 「未コミットのタスクファイルがあります。PR を準備する前にコミットしますか？」 停止して返答を待ってください。 PR 作成の承認だけでは、このコミットは承認されていません。

• ユーザーが同意した場合は、意図した未追跡ファイルも含め、該当ファイルのみをステージングしてコミットします。両方の操作で明示的なパスを使用してください。git commit --only を使うと、ステージング済みの無関係なファイルをコミット対象から除外できます。対象を限定したコミットの例を参照してください。
• ユーザーが断った場合は、ファイルに手を加えず、作成を停止します。
• 下書きのみのモードでは、ステージングもコミットもせず、予定されている変更を説明します。

ステップ 2 — 変更内容を読む

次の順序でベースを決定します。

1. ユーザーまたは呼び出し元のワークフローが指定したベース。
2. 利用可能な場合は、ブランチに既存の PR があればそのベース、または現在のタスクコンテキスト。
3. git symbolic-ref --short refs/remotes/origin/HEAD。それがなければ origin/master、それもなければ origin/main。

ブランチのベースには origin/<name> を使用し、/ を含む名前はそのまま保持します。別のブランチを示すアップストリームは、フォールバックを使う前に確認するためのベース候補です。origin/<current branch> はベースではありません。フォールバックが誤ったリリース系列やメンテナンス系列を示している場合は、ベースを尋ねてください。

MB=$(git merge-base <base> HEAD) を設定します。同じ範囲について、ファイル一覧と完全な差分を読み取ります。

• コミット済みの変更（ステップ 1 の後に作成モードで行った変更を含む）：git diff <base>...HEAD。
• 未コミットのタスク作業がある下書き：git diff $MB に加え、タスクの未追跡ファイル全体。

その範囲に対して --name-status と --stat を使用します。必要に応じて周辺のコードも読み、無関係なローカル編集は説明から除外します。タスクの変更がない場合は、説明する変更がないことを報告して停止します。差分が空でも、ベースが誤っているとは限りません。

ステップ 3 — テンプレートを選ぶ

.github/、リポジトリのルート、または docs/ の下にある PULL_REQUEST_TEMPLATE.md またはその小文字表記のファイルと、それらの PULL_REQUEST_TEMPLATE/ ディレクトリにあるテンプレートを探します。同程度に適用できるテンプレートが複数ある場合は、どれを使うか尋ねてください。

作業ツリーからテンプレートを読み取ります。見出し、順序、チェックリストの文言は維持し、作成者向けの指示を実際の内容に置き換えます。チェックボックスはすべて未選択のままにします。 テンプレートがない場合は、デフォルトを使用します。チェックリストは付けず、「目的」「アプローチ」と、必要に応じて「実装の詳細」で構成します。

ステップ 4 — 説明を作成する

変更内容を表す、80 文字未満を目安にした短いセンテンスケースのタイトルを作成します。 ユーザーが指定した Jira キー、タスクのコミットメッセージの先頭にある Jira キー、またはブランチ名の一部として 使われている Jira キー（BF-1523、MODUSERSKC-12）を使用します。これらの情報源が矛盾する場合は、一度だけ確認します。 通常の文章に含まれる UTF-8 や HTTP-413 などのトークンは、チケット識別子ではありません。 キーが判明している場合は KEY: <summary> の形式にし、本文に Jira リンクを含めます。 キーがない場合は通常のタイトルを使用し、リンクを省略します。質問する必要はありません。

選択したテンプレートに、問題と変更後の動作を記入します。デフォルトのテンプレートでは、 Purpose に 1～2 文、Approach に 2～3 文を記述します。変更に重要な要素が複数ある場合は、 簡潔な実装箇条書きを追加します。技術用語や主張はコードで裏付けてください。 検証については、このセッションで結果を確認できた場合、またはユーザーから結果が提示された場合にのみ記載します。

本文が選択したテンプレートと変更内容に合っていることを確認します。 下書きのみの依頼では、タイトルと本文を提示して終了します。作成モードの場合は、ステップ 5 に進みます。

ステップ 5 — PR を確認して作成する

GitHub を呼び出す前に、対象リポジトリで有効な gh auth status を確認します。 ローカルの .envrc によりアカウントが上書きされることがあります。認証が利用できない場合や、 想定と異なる場合は、説明を提示して問題を報告します。

git branch --show-current で現在のブランチを確認します。作成には、ベースブランチとは異なる 名前付きのフィーチャーブランチが必要です。次のコマンドで実際のリモート先端を確認します。 git ls-remote origin "refs/heads/<current branch>" の結果を git rev-parse HEAD と比較します。 ブランチが存在しない場合、またはローカルのコミットが先行している場合は、プッシュが必要です。 リモートと分岐している場合は、強制プッシュせずに停止して状況を報告します。

最終的なタイトルと本文を提示し、プッシュが必要かどうかを伝え、「Create the PR?」と尋ねます。 この文面の承認を待ってください。この承認には、現在のブランチの必要なプッシュも含まれます。 プッシュの許可を別途求めないでください。 この正確なプレビューがすでに承認されている場合は、その承認を再利用します。

承認を待っている間にタスクファイル、HEAD、ベースブランチ、またはテンプレートが変更された場合は、 該当するステップを再確認し、更新したプレビューを提示します。それ以外の場合は、準備を繰り返さずに進めます。

必要な場合に限り、宛先を明示してプッシュします。

git push origin "HEAD:refs/heads/<current branch>"

その後、リポジトリ外のファイルに承認済みの本文を保存して PR を作成します。

gh pr create --base <base branch name> --head <current branch> --title "<title>" --body-file <path>

ベースブランチ名の先頭にある origin/ だけを削除し、残りの / は保持します。 明示的な --head により、gh が暗黙的にプッシュすることを防ぎます。 PR の URL を返します。プッシュまたは作成に失敗した場合は、停止して説明と問題を返します。

操作範囲を守る

ビルド、テスト、リンター、ジェネレーターを実行したり、NEWS.md を編集したりしないでください。ブランチの切り替え、 スタッシュ、リセット、クリーン、強制プッシュ、Git 設定の変更、拒否されたフックや権限の回避を行わないでください。 PR の文面に秘密情報やツールの帰属情報を含めないでください。