backport-pr-assistant

CockroachDB バックポートアシスタント

ユーザーが、プルリクエストを古いリリースブランチへバックポートするのを支援します。特に、コンフリクトの解決が必要な場合に役立ちます。

バックポート CLI ツールリファレンス

バックポートツールがブラウザウィンドウを開かないよう、必ず --no-browser を指定してください。--no-browser が認識されない場合は、ユーザーが古いバージョンのツールを使用しています。go install github.com/cockroachdb/backport@latest を実行してツールをアップグレードしてから、再試行してください。

基本的な使い方:

backport --no-browser <pull-request>...              # Backport entire PR(s)
backport --no-browser <pr> -r <release>              # Target specific release (e.g., -r 23.2)
backport --no-browser <pr> -b <branch>               # Target specific branch (e.g., -b release-23.1.10-rc)
backport --no-browser <pr> -j "justification"        # Add release justification
backport --no-browser <pr> -c <commit> -c <commit>   # Cherry-pick specific commits only
backport --no-browser <pr> -f                        # Force operation

コンフリクトの解決:

backport --continue                     # Resume after resolving conflicts
backport --abort                        # Cancel in-progress backport

よく使う例:

backport --no-browser 23437                          # Simple backport
backport --no-browser 23437 -r 23.2                  # To release-23.2 branch
backport --no-browser 23437 -j "test-only changes"   # With justification
backport --no-browser 23437 -b release-23.1.10-rc    # To specific release candidate branch

対象ブランチの決定

ユーザーが特定のリリースブランチを指定した場合は、そのブランチをそのまま使用します。「すべてのブランチへバックポート」や「サポートされているすべてのリリースへバックポート」のように、バージョンを個別に挙げずに指示された場合は、CockroachDB のリリースサポートポリシーページを取得して、現在もサポートされているブランチを判断します:

https://www.cockroachlabs.com/docs/releases/release-support-policy

このページには Supported versions と Unsupported versions の 2 つの表があります。バックポートするのは、Maintenance Support end date がまだ過ぎていないバージョンだけにしてください。Assistance Support フェーズのバージョンは重大なセキュリティ修正のみを受け取り、一般的なバグ修正のバックポートは受け取りません。Unsupported versions の表に載っているバージョン（EOL）はスキップしてください。Innovation リリースには特に注意してください。サポート期間が短く Assistance Support フェーズもないため、最近 EOL になっている可能性があります。

ワークフロー

最初のバックポートを開始する前に、リリースの正当化理由（例: 「データ損失の可能性があるバグ修正」「テストのみの変更」「セキュリティパッチ」）をユーザーに確認してください。すべてのバックポート PR で同じ正当化理由を使用してください。backport を実行するたびに -j で渡してください。

1. バックポートを開始する: 対象ブランチに対して backport --no-browser <pr> -r <release> -j "<justification>" を実行します
2. コンフリクトが発生した場合: ツールは停止し、コンフリクトしているファイルを一覧表示します
3. コンフリクトを分析する: コンフリクトしているファイルを読み、ブランチ間で何が異なるのかを理解します
4. コンフリクトを解決する: ファイルを編集して解決し、解決済みのファイルを git add します
5. 続行する: backport --continue を実行して再開します
6. さらにコンフリクトが発生した場合: 手順を繰り返します
7. 完了: バックポートツールがコミットをチェリーピックし、ブランチをユーザーのフォークにプッシュします
8. PR の作成: ユーザーが明示的に依頼した場合にのみ PR を作成します。デフォルトでは、バックポートツールがブランチをプッシュした時点で停止します。ユーザーが PR の作成を依頼した場合は、gh pr create を使用してください（後述の「バックポート PR の作成」を参照）

バックポート PR の作成

ユーザーが明示的に依頼した場合にのみ PR を作成してください。gh pr create を以下の規則に従って使用します。

PR タイトルの形式:

release-XX.X: <original PR title>

タイトルは、リリースブランチの接頭辞、コロン、スペース、そして元の PR のタイトルをそのまま記載したものです。たとえば、元の PR タイトルが "keys: handle case where keys targeted by GC request straddle header" で、対象ブランチが release-24.3 の場合、バックポート PR のタイトルは次のようになります:

release-24.3: keys: handle case where keys targeted by GC request straddle header

PR 本文の形式:

バックポートツールが使用する標準的な本文の形式に合わせてください:

Backport N/N commits from #<original-pr> on behalf of @<user>.

----

<original PR commit messages or body>

----

Release justification: <justification>

gh pr create の実行例:

gh pr create \
  --repo cockroachdb/cockroach \
  --base release-24.3 \
  --head <user>:backport24.3-<pr-number> \
  --title "release-24.3: <original title>" \
  --body "<body following the format above>"

コンフリクト解決のガイドライン

そのまま解決できる単純なコンフリクト:

• import 文のコンフリクト
• 単純な変数名の変更
• 基本的な書式の違い
• 明らかな軽微な API シグネチャの変更

ユーザーに指示を仰ぐべき複雑なコンフリクト:

• 重要なロジックの変更を伴うコンフリクト
• 対象ブランチに存在しない依存関係
• 大幅な修正が必要な API の変更
• 相互に依存する変更を含む複数のコンフリクトファイル
• 対象ブランチに適さないかもしれない変更

コンフリクトを解決する際の手順

1. コンフリクトの内容を説明する - 関連するコードの箇所を示します
2. 理由を説明する - コンフリクトの原因となった、ブランチ間の違いを説明します
3. 解決策を提案する - 複雑な場合は、解決策を提案するか、指示を仰ぎます
4. 解決後: git add <files> を実行してから backport --continue を実行します