resolve-backport-conflicts

Mergify がブランチをどのような状態にするか

Mergify は cherry-pick でプルリクエストをバックポートします。cherry-pick でコンフリクトが発生すると、Mergify はコンフリクトしたファイルに対して git add を実行し、未解決のままコミットします。その結果、ブランチには生のコンフリクトマーカーが残ります。

<<<<<<< HEAD
content of the target branch, such as version-16-hotfix
=======
content of the commit under backport
>>>>>>> <sha> (commit subject)

HEAD 側はターゲットブランチです。>>>>>>> 側はバックポート対象のプルリクエストです。どちらかの側がデフォルトで優先されるわけではありません。

手順

1. プルリクエストをチェックアウトする

プルリクエストを所有するリポジトリ内で作業してください。現在のディレクトリが別のリポジトリの場合は、正しいリポジトリをスクラッチパッドディレクトリにクローンしてください。

gh pr view <pr-url> --json number,title,body,baseRefName,headRefName,headRepositoryOwner,url
gh pr checkout <pr-url> --force

--force フラグは、古くなったローカルブランチをプルリクエストの HEAD にリセットします。作業ツリーに変更がある場合は、作業を中止してユーザーに伝えてください。ユーザーの作業を破棄してはいけません。

2. 元のプルリクエストを読む

Mergify の説明には、This is an automatic backport of pull request #<N> という行があります。この行から番号を読み取ってください。この行がない場合は、ブランチ名 mergify/bp/<branch>/pr-<N> から番号を読み取ってください。

gh pr view <N> --json title,body,url
gh pr diff <N>

この差分には、バックポートの意図が示されています。ファイルを編集する前に、すべて読んでください。

3. すべてのマーカーを探す

git grep -nE '^(<{7}|={7}|>{7})' -- . || echo "no markers"
git diff HEAD~1 --stat
git log -1 --format=%s

最後のコマンドで、HEAD が Mergify のコンフリクトコミットであることを確認できます。残っている .rej ファイルや .orig ファイルも探してください。

4. 各コンフリクトを解決する

1. このブランチで何が行われるコードなのか分かるまで、コンフリクトの周辺を読みます。
2. ターゲットブランチ側を基点にします。これはリリースブランチに現在含まれている内容を示します。
3. 元のプルリクエストの変更を、その側に適用します。
4. 元のプルリクエストの差分に含まれていない行はすべて削除します。
5. 3 つのマーカー行を削除します。

手順 4 が最も重要です。コンフリクトのハンクには、ソースブランチの後続コミットに含まれる無関係な変更が紛れ込んでいます。名前が変更されたヘルパー、新しい API、無関係なリファクタリングなどが、このように入り込みます。これらはリリースブランチに含めてはいけません。

バックポートに必要な関数やモジュールがターゲットブランチにない場合は、代わりのものを書かないでください。不足していることを報告し、どう進めるかユーザーに確認してください。

Mergify は、別のコミットに属するコンフリクトのないハンクもステージします。これを見つけるには、コンフリクトコミット全体を元のプルリクエストの差分と比較してください。一致しないハンクは元に戻してください。

5. 検証する

git grep -nE '^(<{7}|={7}|>{7})' -- .
git diff HEAD

最初のコマンドは何も出力してはいけません。2 つ目のコマンドが出力するすべての行を読んでください。git diff HEAD~1 と gh pr diff <N> を比較します。ブランチの違いを除き、2 つの差分は一致していなければなりません。

リポジトリにリンターやフォーマッターがある場合は、変更したファイルに対して実行してください。

6. コミットしてプッシュする

git add <modified files>
git commit -m "chore: resolve conflict"
git push <remote> HEAD:<headRefName>

リモートを選ぶには、手順 1 の headRepositoryOwner を git remote -v の出力と照合してください。Mergify のブランチはフォークではなく、アップストリームリポジトリにあります。強制プッシュは絶対にしないでください。

7. conflicts ラベルを削除する

cherry-pick が失敗すると、Mergify は conflicts ラベルを追加します。このラベルは誰かが削除するまで残ります。プッシュが成功した後、かつマーカーが残っていない場合に限り、ラベルを削除してください。

gh pr edit <pr-url> --remove-label conflicts

プルリクエストにこのラベルが付いていない場合、コマンドは失敗します。この失敗は問題ありません。すべてのコンフリクトを解決できなかった場合は、ラベルを残してください。

8. 要約する

次の点をユーザーに報告してください。

1. バックポートのプルリクエストと元のプルリクエスト。
2. コンフリクトがあった各ファイルと、その解決方法を一行で説明したもの。
3. 無関係として破棄した変更と、その理由。
4. 解決できなかった各コンフリクト。
5. プッシュしたコミットの sha。

事実を伝えてください。解決方法が判断を伴う場合は、そのことを明記してください。