x**3な人生

基本的にはメモ

DPDKにパッチを送るためのメモ

はじめに

DPDKにパッチを送るのに'git send-email'を使う必要があるのですが、慣れるまでにすぐ忘れてしまったり、間違うと変なパッチを送って取り返しがつかなくなってしまうので、自分のためにメモしておきます。
参考にする場合は自己責任でお願いします。

とりあえずUbuntuで試した結果を書きます(コミットメッセージのエディタはvim)。他の環境で試してみて違うところがあったら追記します(TODO)。

パッチを作成する

`git format-patch`を使うと1コミットごとにパッチファイルを作成することができます。また複数のパッチファイルをまとめて作成することも可能です。
複数のパッチファイルを送付する場合、カバーレターと呼ばれる要約を記述するためのファイルを最初に追加するようにします。これはパッチの受け取り手に対して理解を促すためで、「いきなり沢山パッチを送られても、、、」となるのを避けるためのものです。

単に最新1コミットのパッチを作成する

対象のコミットと出力先ディレクトリを指定します。ディレクトリが存在しない場合は作成してくれます。
これは最新のコミット('-1'で指定)を'patches'ディレクトリへ出力する例です。

$ git format-patch -1 -o patches
patches/0001-....patch

複数のパッチを作成する

先ほどの'-1'を変更することで、最新のコミットからさかのぼって複数のパッチを作成することができます。
カバーレターを付けて最新3コミットのパッチファイルを作成するには次のようにします。

$ git format-patch -3 -o patches --cover-letter
patches/0000-cover-letter.patch
patches/0001-....patch
patches/0002-....patch
patches/0003-....patch

'0000-cover-letter.patch'がカバーレターです。このファイルはパッチを送付する前に編集する必要があります。
'*** SUBJECT HERE ***'と'*** BLURB HERE ***'の2箇所を削除して、タイトルと説明文を追記します。これらを削除しないと'git send-email'での送信時にエラーとなります。

From a8ed80b425c7a81fab8dc72a7ce1aba9aa9d... Mon Sep 17 00:00:00 2001
From: [作成者の名前] <[メールアドレス]>
Date: Sun, 18 Feb 2018 00:10:02 +0900
Subject: [PATCH 0/3] *** SUBJECT HERE *** 

*** BLURB HERE ***

[作成者の名前] ([パッチ数]):
...

任意のコミットのパッチを作成する

前の例でパッチ数を指定した'-1'や'-3'ではなく、コミットIDを指定することにより任意のコミットのパッチファイルを作成することもできます。
例えば以下のようにしてコミットIDを確認した場合、4番目の'7f7cfda'を指定することで最新3つのパッチを作成できます。

git log --oneline
a8ed80b ...
3c9d1c5 ...
8627ed9 ...
7f7cfda ...
4b60fc2 ...
...

出力されるパッチファイルは先ほどと同じです。パッチ数が多い場合にはいちいち数えるよりもこちらのほうが簡単です。

$ git format-patch 7f7cfda -o patches --cover-letter
patches/0000-cover-letter.patch
patches/0001-....patch
patches/0002-....patch
patches/0003-....patch

また2つのコミットIDを指定すれば、その間のコミットだけを出力することもできます。例えば最新から2、3番めのコミットだけを用いる場合は'7f7cfda..3c9d1c5'(4番目..2番目)を指定します。

git format-patch -o patches0 7f7cfda..3c9d1c5 --cover-letter
patches/0000-cover-letter.patch
patches/0001-....patch
patches/0002-....patch

パッチを送付する前に

必ずdevtools/checkpatches.shを使いましょう。もし警告やエラーが出力された場合は、該当箇所を修正してコミットし、再度パッチを作成します。
問題がなければ以下のようになります。

$ /path/to/checkpatches.sh patches/*

3/3 valid patches

パッチを送付する(1回目)

'git send-email'によりパッチを送付します。新規にパッチを送付するには宛先とパッチファイルを指定します。またディレクトリを指定することで一度にすべてのパッチを送付することもできます。

$ git send-email --to [宛先アドレス] --annotate patches/

'--annotate'は送信する前にパッチの確認と編集を行うためのオプションです。送信前に確認できていれば特に必要はありませんが、チェック漏れを防ぐ意味でも付与しておくほうが良いです。

宛先が複数ある場合は','で区切ることで指定可能です。また'--to'だけでなく'--cc'なども使用できます。

$ git send-email --to aaa@example.com,bbb@example.com --cc ccc@example.com --annotate patches/

パッチを送付する(2回目以降)

送付したパッチに何らかの不備があり修正を求められることもあります。このような場合、新しく別のパッチを送付するのではなく、バージョンを付与して更新パッチであることを明記します。

更新パッチの作成

例えばバグを修正してコミットを訂正した場合、'git format-patch'にオプション'-v2'を追加してパッチを作成します。作成されたパッチには'v2-'という文字列が追加されています。カバーレターの編集を忘れないようにします。

$ git format-patch -3 -o patches --cover-letter -v2
patches/v2-0000-cover-letter.patch
patches/v2-0001-....patch
...

さらに変更が必要な場合は、バージョンを'-v3'、'-v4'のように更新していきます。

更新パッチの送付

更新パッチは以前のメールへのリプライとして送付します。'--in-reply-to'オプションは以前のメールを特定するためのもので、ここにメッセージIDを指定します。

$ git send-email --to [宛先アドレス] --annotate --in-reply-to [メッセージID] patches/

以前のメールのメッセージIDを確認するにはソースを参照する必要があります。'Subject'のすぐ後ろ辺りに'Message-Id: <...>'という行がありますので、'<>'で囲まれた文字列をメッセージIDとして用います。

...
Subject: [PATCH 0/2] Update patches for ...
Date: Sun, 18 Feb 2018 00:54:39 +0900
Message-Id: <...>
...

(参考)パッチ作成と送付を一度に行う

checkpatches.shでのチェックを飛ばすことになるので禁じ手ですが、'git send-email'から一度に両方行うことも可能です。
例えば最新の3コミットをカバーレターを付けて送付する場合は以下のようにします。

$ git send-email -3 -to [宛先アドレス] --cover-letter --annotate

カバーレターの編集画面が開きますので、'Subject:'の'*** SUBJECT HERE ***'と本文の'*** BLURB HERE ***'を両方とも削除して、それぞれメッセージを追記します。

カバーレターの編集を終えてエディタを終了しようとすると、'--annotate'を指定してるので「編集すべきファイルがあと3個あります」と言われます。
パッチファイルは'/tmp'の一時ディレクトリに作成されていて、必要に応じてこれらを開いて編集を続けます。もし編集が不要なら、そのままもう一度エディタを終了します。
編集が終わるとメール送信のメッセージが表示されます。

...
Send this email? ([y]es|[n]o|[q]uit|[a]ll): 

最後にyesもしくはallで送信します。

以上