shagghiesuperstar/hermes-skills

ドキュメントのみのPR一括マージ

概要

多数の小さなドキュメントプルリクエストは、1つにまとめてレビューする方が効率的です。この手順では、レビュー済みのドキュメントのみのプルリクエストからファイルをコピーし、1つの新しいドラフトプルリクエストに、ソースごとに1コミットずつまとめます。ファイルの内容はそのままコピーされ、編集は行われません。ソースプルリクエストはそのまま残ります。レビュアーが1つのバッチプルリクエストをマージすると、ソースプルリクエストはそれぞれの状態に応じてクローズされます。この手順による操作は行いません。

使用するタイミング

• 複数のオープンなドキュメントプルリクエストがレビューを通過し、それぞれがドキュメントパスのみに影響する場合。
• レビュアーがそれらをまとめた1つのプルリクエストを依頼した場合。

コード、設定、またはレビューを通過していないソースプルリクエストには使用しないでください。

機能

• スクラッチワークツリーを使用するため、現在のチェックアウトには影響しません。
• 各ソースプルリクエストの状態、ベース、先頭、ファイルリストのライブスナップショットを取得し、フェッチされた先頭コミットと照合します。
• クローズ済み、ドキュメントフォルダ外のパス、メインブランチとの衝突、別のオープンPRとの衝突に対するスキップルール。
• マージされるソースごとに1コミットを作成し、不正なソースで処理を停止するアサートを含みます。
• プッシュ前の変更パスに対するゲートと、すべてのファイルのblobをソースの先頭と比較する検証ブロック。

利点

• 不正なソースがある場合、部分的にマージされることなく処理が停止します。
• マージされたすべてのファイルの内容がソースと同一であることが証明されます。
• スキップされたプルリクエストは理由とともにリストされるため、何も見逃されません。
• バッチプルリクエストはドラフトとして作成されるため、レビュアーが最終判断を下します。

手順

1. スクラッチワークツリーで作業する。 メインブランチとソースプルリクエストの先頭をフェッチし、スクラッチフォルダにメインブランチから新しいブランチを作成します。

   git fetch origin main '+refs/pull/*/head:refs/remotes/origin/pr/*'
   git worktree add -b <batch-branch> <scratch-dir>/wt origin/main
   

   HTTPSのフェッチまたはプッシュが認証で失敗した場合は、そのコマンドだけをコードホストのCLIに設定されたcredential helper、例えば -c credential.helper= -c 'credential.helper=!gh auth git-credential' を使用して実行します。保存された設定は変更せず、トークンも出力しないでください。

2. ライブ状態を一度だけスナップショットする。 各ソースプルリクエストについて、その状態、ドラフトフラグ、ベースブランチ、先頭コミット、ファイルリストを読み取ります。また、衝突チェックのためにオープンなプルリクエストもリストします。各ソースの先頭コミットがフェッチされた refs/remotes/origin/pr/<n> コミットと一致することをアサートします。

3. 番号順にスキップまたはマージを決定する。 以下のいずれかに該当する場合、プルリクエストをスキップし、理由を記録します。

   • オープンでない。
   • いずれかのパスがドキュメントフォルダの外にある。
   • いずれかのパスがすでにメインブランチに存在する。メインブランチにすでにあるパスについては、blobを比較します。内容が同じであれば、以前にマージされたことを意味します。内容が異なる場合は、リベースが必要です。
   • 別のオープンなプルリクエストがいずれかのパスを変更している。

4. 各プルリクエストを1コミットとしてマージする。 マージする各プルリクエストについて、そのファイルを先頭コミットからチェックアウトし、プルリクエストを表すメッセージでコミットします。これを、プルリクエストがオープンであること、先頭が一致すること、パスがドキュメントフォルダ以下であること、およびそれらのいずれもメインブランチにないことをアサートするループ内で実行します。アサートに失敗した場合、処理は停止します。

   git checkout <head-commit> -- <paths>
   git commit -m "docs: land #<n>"
   

5. プッシュ前に変更をゲートする。 ドキュメントフォルダ外の変更ファイル数はゼロでなければなりません。変更されたファイルの総数は、プルリクエストごとのパス数の合計と等しくなければなりません。

6. 検証ブロックを作成する。 各プルリクエストとその各パスについて、バッチブランチの HEAD のblobとソース先頭のblobを比較します。プルリクエストごとに1行、その先頭、パス数、blob数、および MATCH を表示し、合計を出力します。ブロックをそのままバッチプルリクエストの説明に貼り付けます。

7. バッチプルリクエストをドラフトとして作成する。 ブランチをプッシュし、メインブランチに対するドラフトを作成します。タイトルには、考慮されたPRの数ではなく、実際にマージされたPRの数が示されます。

   gh pr create --draft --base main --title "docs: land <k> reviewed docs PRs" --body-file <body-file>
   

8. 説明文を書く。 ドキュメントのみの差分のためビルドをスキップしたこと、ファイル数と先頭が記載されたマージされたプルリクエストのリスト、理由付きのスキップされたプルリクエスト、レビュアーへのフラグ、および検証ブロックを含めます。新しいプルリクエストの状態を再確認し、メインブランチに対するドラフトであることを確認します。

落とし穴

• ドラフトルールを無視すること。 実行の指示でレビュー依頼可能なプルリクエストを求められる場合があります。実行ルールで別段の指示がない限り、ドラフトとして作成し、その旨を説明文に記載します。
• 別のブランチをベースとするソースプルリクエスト。 そのファイルはすべてのパスルールを通過しますが、メインブランチにマージすると、プルリクエストの意味が変わります。ルールで許可されている場合のみ含め、削除する正確なコミットをフラグとして付けます。
• マージベースがない場合。 そのようなプルリクエストではマージベースのルックアップが失敗し、ベースとの差分がエラーになります。パスのソースとしてライブファイルリストを使用します。マージベースが存在する場合にのみ、マージベースとの差分をクロスチェックします。
• 部分的なマージ。 メインブランチにすでにあるファイルを変更するプルリクエストは、他のファイルが新規であってもスキップできます。一部だけをマージしないでください。
• 欠落パスエラーで出力が埋め尽くされること。 パスがメインブランチに存在するかどうかをチェックすると、存在しないパスごとにエラーが出力されます。そのようなチェックでは、標準エラーを /dev/null にリダイレクトします。
• 最終レポートのパディング。 スキップされたリストとその理由、フラグ、検証の合計を報告します。すべてのファイルをリストしないでください。
• グラフまたはインデックスがない場合。 コードインテリジェンスインデックスがリポジトリで利用できない場合は、レポートにその旨を記載し、パスルールをスキップしないでください。

検証

• バッチプルリクエストはメインブランチに対するドラフトであること。
• マージされたすべてのファイルのblobが、検証ブロックに示されているようにソースの先頭と一致すること。
• 変更されたファイルがドキュメントフォルダ外に存在しないこと。
• スキップされたすべてのプルリクエストに説明文内で理由が記載されていること。
• ソースプルリクエストは変更されていないこと。この手順では、ソースプルリクエストのマージ、承認、クローズ、コメントは行われません。