triage-prs

PR のトリアージ

目的

オープンな PR のバックログを、1 回の集中セッションでマージ済みの集合に変えます。追跡可能で再開可能な計画 (<VERSION>_PR_TRIAGE.md) を作成し、それを実行します — 必要な箇所ではリベースし、分離しても安全なバッチでマージし、マージ後のフォローアップを適用し、superseded または部分的にしか適用できない PR は投稿者へのクレジットを添えてクローズします。

このスキルは draft-release-notes と release-bump と組み合わせて使います: まずトリアージし、次に新しい main に対してノートをドラフトし、それからリリースを切ります。

使用するタイミング

• マイナーまたはメジャーリリースの前に、オープンな PR が 10 件以上たまっているとき
• 何が取り込まれるかの筋道を失わずにマージを進めたいとき
• すべての PR を自分で深くレビューすることはできないと分かっていても、重要なサブセットを素早く取り込む必要があるとき

前提条件

• リポジトリに対して認証済みの gh CLI
• PR レビュー専用のワークツリー (main をコントリビュータのブランチのチェックアウトで汚染しないため)
• 対象バージョンが明確であること — トリアージドキュメントはその名前で命名されます (例: 0.4.0_PR_TRIAGE.md)

ワークフロー

1. 分離された PR レビュー用ワークツリーをセットアップする

git worktree list  # check for stale ones first
git worktree prune
git worktree add ../voicebox-pr-review -b pr-review-<VERSION> main

メインのワークツリーはリリース準備作業 (changelog のドラフト、main への直接のフォローアップ) 用に取っておきます。レビュー用ワークツリーは gh pr checkout 用に取っておきます — チェックアウトのたびに HEAD がコントリビュータのブランチへ移動するため、これをメインのワークツリーで行うのは避けたいからです。

2. すべてのオープンな PR のメタデータを収集する

gh pr list --state open --limit 50 --json \
  number,title,author,isDraft,mergeable,mergeStateStatus,files,additions,deletions,reviewDecision,statusCheckRollup,maintainerCanModify \
  --jq '.[] | {num: .number, title, author: .author.login, mergeable, state: .mergeStateStatus, canModify: .maintainerCanModify, changes: "+\(.additions)/-\(.deletions)", files: [.files[].path]}'

各 PR について必要なもの:

• サイズ (+additions/-deletions)
• マージ可能な状態 (CLEAN、UNSTABLE、DIRTY = コンフリクト、UNKNOWN = GitHub がまだ計算中)
• そのブランチでメンテナの編集が許可されているか (後で投稿者のためにリベースする場合に必要)
• 変更されたファイルパス (PR 間の重複に気づくのに役立ちます)

main へのプッシュ直後は UNKNOWN がよくあるので、とりあえずマージを試して確認します。

3. 階層に分類する

各 PR をちょうど 1 つのバケットに振り分けます:

階層 1 — マージ: 小さく、マージ可能で、実際のバグを修正し、CI がクリーンで、レビューコストが低いもの。ワンライナー、依存関係の緩和、的を絞った安全性の強化。これらは簡単な勝ち筋です。

階層 2 — 候補、レビュー: 中規模 (50〜200 行)、より広い範囲に触れ、妥当に見えるがより注意深い読解が必要なもの。製品の方向性に合致する新しいユーザー向け機能。

Supersede: その修正や機能がすでにマージ済みの何かでカバーされているもの。supersede した PR を指すコメントを添えてクローズします。注意深く確認してください — 「似たタイトル」は証拠にはなりません。実際の差分を比較しましょう。

次のリリースへ延期: 大きな機能、dirty なコンフリクト、ドラフト PR、リスクを招く形でリリースパイプラインに触れるもの。これらをスピードランでマージしないでください — 専用の集中が必要です。

4. トリアージドキュメントを書く

PR レビュー用ワークツリーのルートに <VERSION>_PR_TRIAGE.md を作成します。構成:

# <Repo> <VERSION> — PR Triage

Working doc for tracking which open PRs land in <VERSION>. Delete after release cut.

Last updated: <DATE>

## Progress

**Tier 1: 0 / N merged**
**Tier 2: 0 / M handled**
**Supersede triage: pending**

---

## Merge for <VERSION> — critical bug fixes

| PR | Status | Size | What it fixes | Why must-have |
|---|---|---|---|---|
| [#123](url) | [ ] | +5/-0 | ... | ... |

## Strong candidate — needs a quick review

| PR | Status | Size | Summary |
|---|---|---|---|

## Close as superseded

| PR | Status | Reason |
|---|---|---|

## Defer to <NEXT_VERSION>

- [#xxx](url) ... — reason

---

## Order of attack

1. Close superseded PRs (one-liner comments)
2. Merge tier-1 in dependency-free batches — check file paths don't overlap
3. Review tier-2 individually
4. Rerun `draft-release-notes` to pick up everything
5. Run `release-bump`

Progress ヘッダーが最も重要な部分です — これはスコアボードであり、セッションが中断された場合にきれいに再開できるようにします。

5. ループを回す — PR ごとに

tier-1 / tier-2 リストの各 PR について:

a. レビュー用 worktree でチェックアウト:

cd ../voicebox-pr-review
git checkout pr-review-<VERSION>  # reset to neutral base
gh pr checkout <N>

b. main..HEAD ではなく、実際のコミットを読む:

git show HEAD                    # the PR's actual changes
git show --stat HEAD             # files touched + line counts

PR ブランチが main より古い場合、git diff main..HEAD でレビューしないでください。その diff には、PR がフォークされた後に main へ取り込まれたすべてのコミットが - (削除) 行として含まれます。3 行の PR が 700 行のリバートのように見えることがあります。これは PR を誤って判断する最も簡単な方法です。

c. 懸念点を評価: 正確性、スコープ、すでにマージ済みの作業との相互作用、バージョン互換性 (例: まだ固定していない依存関係のバージョンを必要とする API は使えない)。

d. ブランチが main より遅れている場合はリベース:

git fetch origin main
git rebase origin/main

これは squash マージの前に不可欠です。GitHub の squash は diff(PR-head, merge-base) を計算します — 古いブランチでは、その diff に間にあるすべてのコミットをリバートする内容が含まれます。リベースするとマージベースが前に進むため、squash がクリーンになります。

e. メンテナによる編集が許可されている場合、リベースをコントリビューターのフォークにプッシュバック:

git remote add <author> https://github.com/<author>/<repo>.git
git fetch <author> <branch>              # get their ref first
git push <author> HEAD:<branch> --force-with-lease

これにより GitHub の PR UI がリベース後の状態と同期し、GitHub 側からのマージがクリーンになります。

f. マージ:

gh pr merge <N> --squash

g. トリアージドキュメントを更新 — チェックボックスを ✅ merged <sha> に切り替えます (gh pr view <N> --json mergeCommit --jq '.mergeCommit.oid[0:7]' の短い SHA を使用)。Progress ヘッダーを更新します。

6. 小さな修正をまとめて処理

変更行数が ≤5 行、CI がクリーン、ファイルパスが重複していない、意図が明らかに正しい PR (例: 1 行の依存関係の緩和、環境変数の追加、import パスの修正) は、PR ごとのレビュー儀式なしで 1 回のループでマージできます:

for pr in 425 384 416 429; do
  echo "=== Merging PR $pr ==="
  gh pr merge $pr --squash
done

その後、それぞれがクリーンに取り込まれたことを確認します:

for pr in 425 384 416 429; do
  gh pr view $pr --json state,mergeCommit --jq "{pr: $pr, state, sha: .mergeCommit.oid[0:7]}"
done

7. マージ後のフォローアップ

既知の軽微な問題 (例: 不完全な dtype マップ、古いセンチネルのクリーンアップ) があっても、マージする価値のある PR があります。マージをブロックせず、直後に通常のブランチ + PR としてフォローアップを適用します:

cd <main-worktree>
git pull --ff-only origin main
git checkout -b fix/<short-name>
# edit...
git commit -m "fix(<area>): <one-liner>"
git push -u origin fix/<short-name>
gh pr create --title "..." --body "Follow-up to #<N>. ..."

両方の SHA をトリアージドキュメントに記録します (✅ merged <pr-sha> + follow-up <pr>)。

main への直接コミットの例外: 明示的でスコープが限定されたポリシー (例: 「リリーススピードラン」) の下でのみ行います。これをデフォルトにしてはいけません。

8. 置き換え: クレジットを示すコメントを付けてクローズ

gh pr close <N> --comment "Closing — superseded by merged #<M> which landed <brief description>. Thanks!"

まず diff を確認してください — 「似たタイトル」だけでは不十分です。PR が部分的に置き換えられている場合 (診断は正しいが、変更の半分だけがまだ必要)、部分適用を行います。

9. 部分適用のパターン

PR に価値のある変更と疑わしい変更がまとめて含まれている場合:

cd <main-worktree>
git pull --ff-only origin main

# Cherry-pick specific files from the PR branch
git checkout <pr-commit-sha> -- <file1> <file2>

# Review the staged changes, adjust as needed
git diff --cached

# Apply any surgical edits to files you don't want to bulk-replace
# (e.g. the PR's file predates a recent main commit you need to preserve)

# Commit with a trailer crediting the original author
git commit -m "$(cat <<'EOF'
<subject>

<body explaining what was kept vs dropped>

Co-Authored-By: <author> <[email protected]>
EOF
)"
git push ...  # branch + PR, unless under the direct-to-main exception

その後、何を適用し何を破棄したかを説明するコメントを付けて PR をクローズし、コミット SHA を参照します。

10. ドキュメントを最新に保つ

すべてのマージ、すべてのクローズ、すべてのフォローアップ → <VERSION>_PR_TRIAGE.md を更新します。このドキュメントはセッションログです。中断して翌日再開する場合、このドキュメントが「今どこにいるか」の唯一の真実の情報源です。

11. トリアージが完了したら

• ドキュメント内のすべての PR が終端ステータス (✅ merged / ✅ closed / deferred) を持つ
• Progress ヘッダーが各 tier について N/N を示す
• 次に実行するスキルは draft-release-notes (新しい main に対して [Unreleased] を再生成)、その後 release-bump

リリースが出荷された後にトリアージドキュメントを削除してもよいし、記録としてバージョン履歴に残してもよいです。

注意点

• 古いブランチでの main..HEAD は嘘をつきます。 ブランチが分岐して以降に main が取り込んだすべてが、削除として表示されます。PR の実際のコミットを確認するには、常に git show HEAD でレビューしてください。
• リベースされていないブランチをスカッシュマージすると、途中の作業が巻き戻ります。 スカッシュは diff(PR-head, merge-base) を計算します。リベースするとマージベースが前に進みます。
• mergeable=UNKNOWN は一時的な状態です — プッシュ後に GitHub が再計算しています。そのままマージを試してください。
• ルートの順序は重要です（FastAPI など）： DELETE /history/failed は DELETE /history/{id} より前に登録する必要があります。そうしないと、パラメータ化されたパスが "failed" を ID として消費してしまいます。
• Apple の -weak_framework は、同じフレームワークに対して順序に関係なく -framework を上書きします — 依存関係がオプションのものをハードリンクしている場合は、cargo:rustc-link-arg=-Wl,-weak_framework,Name を介して使用してください。
• 依存関係のバージョン下限は、適用できる内容を制約します。 torch_dtype= → dtype= のような kwarg の名前変更を受け入れる前に、最小バージョンのピンがそれをサポートしているか確認してください。PR の半分だけをチェリーピックするのが正しい対応であることもあります。
• cpal::Stream や同様の !Send なオーディオ型は、await ポイントや spawn_blocking をまたぐことができません。「理想的ではないが正しい」同期待機が、利用可能な最善の修正であることもあります。指摘はしても、ブロックはしないでください。
• PyTorch のナイトリービルドはリリースには出荷できません — 非決定的で、実行ごとにリグレッションする可能性があります。PR が GPU の問題を修正するためにナイトリーへの切り替えを提案している場合は、代わりに TORCH_CUDA_ARCH_LIST=...+PTX を優先するか、安定版のサポートを待ってください。

正規コマンドリファレンス

# Bulk PR metadata
gh pr list --state open --limit 50 --json number,title,author,mergeable,mergeStateStatus,additions,deletions,maintainerCanModify,files

# Detailed single-PR view
gh pr view <N> --json body,author,headRefName,baseRefName,mergeable,maintainerCanModify,files,statusCheckRollup

# The actual commit, not the branch-vs-main diff
git show HEAD
git show --stat HEAD
gh pr diff <N>

# Rebase contributor branch onto current main
git fetch origin main && git rebase origin/main

# Push rebase back to contributor fork (maintainerCanModify=true required)
git remote add <author> https://github.com/<author>/<repo>.git
git fetch <author> <branch>
git push <author> HEAD:<branch> --force-with-lease

# Merge
gh pr merge <N> --squash

# Confirm merge SHA for triage doc
gh pr view <N> --json state,mergeCommit --jq '{state, sha: .mergeCommit.oid[0:7]}'

# Close superseded
gh pr close <N> --comment "Closing — superseded by merged #<M>. Thanks!"

補足

• 古いブランチを main..HEAD でレビューしないでください。 これはこのスキルで最も重要な一行です。
• トリアージドキュメントがセッションの状態です。 ドキュメントを失えば、セッションを失います。アクションのたびに更新してください。
• 部分適用であってもコントリビューターの功績を認めてください。 Co-Authored-By: トレーラーを使用し、適用されたコミットにリンクするコメントを閉じてください。
• 完璧を出荷の敵にしないでください。 「壊れている」から「軽微な既知の問題はあるが動作する」への修正は、厳密には改善です。問題を指摘し、フォローアップを起票し、修正をマージしてください。