My First Contribution to the Git Project

このチュートリアルは、あなたがGitを使用してソースコードを管理することにすでにかなり精通していることを前提としています。 Gitワークフローの手順はほとんど説明していません。

このチュートリアルは、以下のドキュメントを要約することを目的としていますが、読めば有用な追加事項を見つけることができるでしょう:

あなたが行き詰まった場合は、以下の場所で助けを求めることができます。

Gitは多くの場所でミラーリングされています。 それらの1つからリポジトリのクローンを作成します。 https://git-scm.com/downloads は、クローンを作成するのに最適な場所の1つがGitHubのミラーであることを示しています。

ソースからGitをビルドするには、あなたはシステムにいくつかの依存関係をインストールする必要があります。 必要なもののヒントについては、外部プログラムとライブラリへのGitの依存関係に関するセクションに細心の注意を払って、 INSTALL を見ることで分かります。 そのドキュメントには、インストールせずに新しく構築したGitを「テスト運転」(test-drive)する方法が記載されています。 これが、このチュートリアルで使用する方法です。

上記手順でGitの新しいクローンを作成して、環境に必要なものがすべて揃っていることを確認してください:

このチュートリアルでは、「Pony Saying ‘Um, Hello’」の略である新しいコマンド git psuh (訳注:pushでは無くてpsuh)を追加します。これは、ユーザーの通常の日常のワークフローで頻繁に呼び出されるにもかかわらず、実装されていない機能です。

(この分野では sl のような人気コマンドの実装の他にも、いくつかの取り組みが見られます。)

まず、変更に取り組むための開発ブランチを作成することから始めましょう。 Documentation/SubmittingPatches によると、まったく新しいコマンドは新機能であるため、master に基づいて作業するのは問題ありません。 ただし、将来のバグ修正などについては、そのドキュメントを確認し、適切なブランチに基づいて作成する必要があります。

このドキュメントでは、すべての作業を、アップストリームプロジェクトの master ブランチを基にして行います。 以下のように、開発に使用する psuh ブランチを作成します:

私達は複数のパッチを含むトピックを同時に、レビューのために送信する方法を示すために、ここでいくつかのコミットを行います。

沢山のサブコマンドが組み込みとして書かれています。つまり、C言語で実装され、メインの git 実行ファイルにコンパイルされているということです。非常にシンプルな psuh コマンドを組み込みで実装することで、コードベースの構造や、内部 APIや、貢献者としてレビュー担当者やメンテナと共にこの変更をシステムに統合するプロセス、を見せることができます。

組み込みサブコマンドは通常、 サブコマンドにちなんで名付けられ、 cmd_ という名前の関数の後にサブコマンドの名前が続く、 builtin/ 内に含まれるソースファイルに実装されます。 したがって、コマンドを builtin/psuh.c に実装するのは理にかなっています。 そのファイルを作成し、その中に、スタイルとシグネチャに一致する関数であなたのコマンドのエントリポイントを記述します:

また、私達は psuhの宣言を追加する必要があります。 builtin.h を開き、宣言をアルファベット順に保つために、 cmd_pull の宣言を見つけ、その直前に psuh の行を追加します。

そして、あなたの push.c に必ず #include "builtin.h" を書き込んでください。

早速、その関数に使い捨てのprintfを追加します。 ビルドルールを追加してコマンドを登録できるようになったので、これは適切な開始点です。

ではビルドしてみましょう。 Makefile を開き、 builtin /pull.o が BUILTIN_OBJS に追加されている場所を見つけ、次に、それと同一の方法でアルファベット順になるように builtin/psuh.o を追加します。それができたら、最上位ディレクトリに移動し、 make を使用してビルドします。 また、 DEVELOPER = 1 変数を追加して、いくつかの追加の警告をオンにします:

素晴らしい! これで、あなたの新しいコマンドそれ自体は問題なくビルドされます。 しかし、まだ誰もそれを呼び出しません。次はそこをいじりましょう。

コマンドのリストは git.c にあります。 commands[] 配列に cmd_struct を追加することで、新しいコマンドを登録できます。 struct cmd_struct は、コマンド名、コマンドの実装への関数ポインタ、およびセットアップオプションフラグを含む文字列を受け取ります。 今のところは push を模倣し続けることしましょう。 cmd_push が登録されている行を見つけてコピーし、 cmd_psuh に変更して、新しい行をアルファベット順に(cmd_pull の直前に)配置します。

オプションは、「Adding a new built-in. 」の「builtin.h」に記載されています。 後でユーザーの現在のワークスペースコンテキストに関するデータを出力したいので、Gitディレクトリが必要です。 そのため、あなたの唯一のオプションとして RUN_SETUP を選択します。

早速、もう一度ビルドしてください。 きれいなビルドが表示されるはずなので、ざっと動かしてみて、それが機能するかどうかを確認しましょう。 bin-wrappers ディレクトリにあなたがテストに使用できるバイナリがあります。

見たまえ！あなたは今、コマンドをゲットしました！よくやった！ では、これをコミットするとしましょう。

git status は、変更された Makefile と builtin.h と` git.c` と 追跡されていない builtin/psuh.c と git-psuh を明らかにします。 まず、無視する必要のあるバイナリを処理しましょう。 エディターで .gitignore`を開き、 `/git-pull を見つけて、新しいコマンドのエントリをアルファベット順に追加します:

git status をもう一度チェックすると、 git-push が追跡されていないリストから削除され、 .gitignore が変更されたリストに追加されていることがわかります。 これで、私達はステージングしてコミットできます:

あなたがコミットメッセージを書くためにエディターが表示されます。 作業中のコンポーネントの名前を含む50桁以下の件名でコミットを開始し、その後に空行1行(常に必須)、そして内容の大部分を提供するコミットメッセージの本文を続けます。 特に、diffから簡単に理解できない場合は、変更の「理由」を明示して提供することを忘れないでください。 コミットメッセージを編集する際に、上記 -s によって追加された Signed-off-by トレーラーを削除しないでください。

早速、 git show を使用して新しいコミットを調べます。 "psuh:" は、主に psuh コマンドを変更したことを示します。 件名は、読者にあなたが何を変更したかについての考えを与えます。 サインオフライン(-s)は、Developer’s Certificate of Origin 1.1(開発者の原産地証明書1.1)に同意することを示します(Documentation/SubmittingPatches [[dco]] ヘッダー参照)。

チュートリアルの残りの部分では、簡潔にするために件名のみをリストします。 ただし、完全に肉付けされたコミットメッセージの例は、このドキュメントの上部にリンクされているリファレンス実装で入手できます。

文字列を出力する以外に、少なくとも何かを行うと便利です。 まず、私たちが得たものすべてを見てみましょう。

あなたの cmd_psuh 実装を変更して、渡された引数をダンプし、既存の printf() 呼び出しはそのままにします:

ビルドして試してみてください。 ご想像のとおり、私達のコマンドの名前を含め、私達がコマンドラインで与えたものはほとんど何でもあります。 (prefix が空の場合は、 cd Documentation/ && ../bin-wrappers/git psuh としてみてください)。 これあまり役に立ちません。 では、私達は他にどのようなコンテキストを取得できるでしょうか？

#include "config.h" 行を追加します。 そして関数本体にちょびっと追加します:

git_config() は、Gitに認識されている構成ファイルから構成を把握し、標準の優先順位ルールを適用します。 git_config_get_string_tmp() は特定のキー("user.name")を検索し、値を提供します。 このような単一キー探索関数は多数あります。 それらすべて(および git_config() の使用方法に関する詳細情報)は、 Documentation/technical/api-config.txt で確認できます。

出力された名前が、実行時に表示される名前と一致することがわかります:

すばらしい！ これで、Git構成の値を確認する方法がわかりました。 これもコミットしましょう。そうすれば、自身の成果を失うことはありません。

さらに、ユーザーの作業コンテキストがどのようなものかを知っておくと便利です。 ユーザーの現在のブランチの名前を出力できるかどうかを見てみましょう。 git status の実装を模倣できます。私達は、出力関数が wt-status.c にあり、ブランチが struct wt_status に保持されていることが分かりました。

wt_status_print() は、 builtin/commit.c の cmd_status() によって呼び出されます。 その実装を見ると、ステータス構成が以下のように入力されていることがわかります:

しかし、ドリルダウンすると、 status_init_config() が git_config() の呼び出しをラップしていることがわかります。 前のコミットで私達が書いたコードを変更してみましょう。

struct wt_status を使用できるように、必ず以下のヘッダーファイルを含めてください:

次に、 あなたの cmd_psuh 実装を変更して、 あなたの struct wt_status を宣言し、準備して、その内容を出力します:

もう一度実行して、確認します。 — これがあなたの現在のブランチの(冗長な)名前です！

これもコミットしましょう。

(コミットしたので)今や、その特定のコミットに関する情報を私達が取得できるかどうかを見てみましょう。

幸いなことに、ここでは、私達のためにいくつかのヘルパーがあります。 commit.h には lookup_commit_reference_by_name という関数があり、ハードコードされた文字列を簡単に設定できます。 pretty.h には、完全な形式のオブジェクトを渡す必要のない非常に便利な pp_commit_easy() 呼び出しがあります。

以下のインクルードファイルを追加します:

次に、 cmd_psuh() の実装内で、宣言とロジックの近くにそれぞれ以下の行を追加します。

struct strbuf は、基本的な char * にいくつかの安全機構(safety belts)を提供します。そのうちの1つは、バッファオーバーランを防ぐための長さのメンバーです。 これは STRBUF_INIT でうまく初期化する必要があります。 char* を渡す必要がある場合は、この点に注意してください。

lookup_commit_reference_by_name は渡された名前を解決するので、その値で遊んでみて、どんなことを思いつくか見てみましょう。

pp_commit_easy は、フォーマット構造体全体ではなく、単一のフォーマット列挙型の省略形をとる pretty.h の便利なラッパーです。 そしてそれから、その省略形に従ってコミットをきれいに印刷(pretty-prints)します。 これらは、多くのGitコマンドで --pretty=FOO で使用できる形式に似ています。

ビルドして実行すると、あなたが例で同一の名前を使用している場合は、あなたが知っている origin/master に最新のコミットの件名が表示されます。ちゃんとできました！ これもコミットしましょう。

素晴らしい！ あなたはコミュニティと共有する準備ができている素晴らしい新しいコマンドを持っています。 だがちょっと待って欲しい。 — これはあまりユーザーフレンドリーではありません。 以下を実行してみます:

あなたの新しいコマンドは文書化されていません！ これを直しましょう。

Documentation/git-*.txt を見てください。 これらは、Gitが知っているサブコマンドのマニュアルページです。 これらを開いてフォーマットを理解するために確認することもできますが、まずは新しいファイル Documentation/git-psuh.txt を作成します。 Gitプロジェクトのほとんどのドキュメントと同様に、ヘルプページは AsciiDoc で作成されています(CodingGuidelinesの「Writing Documentation」セクションを参照)。 以下のテンプレートに従ってあなた独自のmanpageを作成します:

注意すべき最も重要な部分は、 = で下線が引かれたファイルヘッダー、NAMEセクション、およびコマンドが引数を取る場合に通常は文法を含むSYNOPSISです。 ドキュメントが他のGitおよびUNIXのmanpageと一致するように、確立されたmanpageヘッダー(well-established manpage headers)を使用するようにしてください。 これにより、ユーザーは必要な情報が含まれていることがわかっているセクションにスキップできるため、ユーザーが楽をできます。

今や、あなたのmanpageを記述したので、明示的にそれをビルドする必要があります。 以下のようにしてAsciiDocを人間が読めるtroffに変換します:

または

これは git help を実行するほど満足のいくものではありませんが、少なくともあなたのヘルプページが正しく表示されていることを確認できます。

トップレベルから make check-docs を実行することで、ドキュメントの適用範囲が良好であることを確認することもできます(つまり、プロジェクトはあなたのコマンドが実装され、ドキュメント化されていることを確認します)。

早速、あなたの新しいドキュメントの変更をコミットします。

./bin-wrappers/git psuh -h を実行してみてください。 コマンドは最後にクラッシュするはずです。 なぜならこれは、 -h が、あなたのコマンドが使用法の出力を処理しなければならない特殊なケースであるためです。

Documentation/technical/api-parse-options.txt をご覧下さい。 これはあなたが扱えるようにする必要があるオプションを引っ張り出すめの便利なツールで、使用法の文字列を受け取ります。

これを使用するには、使用文字列のNULLで終了する配列と builtin_psuh_options 配列を準備する必要があります。

#include "parse-options.h" 行を追加します。

グローバルスコープで、あなたの使用法文字列の配列を追加します:

次に、あなたの cmd_psuh() 実装内で、 option 構造体を宣言して入力できます。 私たちのものはかなり退屈ですが、 parse_options() をより詳細に調べたい場合は、さらに追加することができます:

最後に、あなたの引数とプレフィックスを出力する前に、 parse-options() の呼び出しを追加します:

この呼び出しにより、あなたの argv パラメーターが変更されます。 argv から options で指定したオプションが削除され、 options エントリからポイントされた場所が更新されます。 必ず あなたの argc を parse_options() の結果に置き換えてください。そうしないと、後で argv をパースしようとしたときに混乱します。

特別な引数 -- に注意する価値があります。 ご存知かもしれませんが、多くのUnixコマンドは「名前付きパラメータの終わり」を示すために -- を使用します — -- の後のすべてのパラメータは単に位置引数として解釈されます。 (これは、通常はフラグとして解釈されるものをパラメーターとして渡したい場合に便利です。) parse_options() は -- に達するとパースを終了し、その後、残りのオプションをそのまま提供します。

今や、あなたは使用上のヒントが得られたので、 command-list.txt から生成される git help git または git help -a で示される一般的なコマンドリストにそれを表示する方法をGitに教えることができます。 あなたは git-pull の行を見つけて、その上に あなたの git-psuh 行をアルファベット順に追加できるようにします。これで、前述のヘルプコマンドのどこに表示されるかに影響を与える、コマンドに関するいくつかの属性を追加できます。 command-list.txt の上部は、各属性の意味に関する情報を共有しています。これらのヘルプページでは、コマンドはこれらの属性に従ってソートされています。 git psuh はユーザー向け、つまり磁器コマンドです。そのため、「mainporcelain」としてマークします。 「mainporcelain」コマンドの場合、 command-list.txt の上部にあるコメントは、オプションで別のリストから属性を追加することもできることを示しています。 git psuh はユーザーのワークスペースに関する情報を表示しますが、何も変更しないので、「info」としてマークしましょう。属性を他の command-list.txt と同一のスタイルに保ち、適宜空白を使用してそれらを整列して記述します:

再びビルドします。 これで、 -h を指定して実行すると、他に何か面白いことが起こる前に、使用法が出力され、コマンドが終了するはずです。 すばらしい！

それでは、これもコミットしておいてください。

Gitのテストは t/ にあり、 t/README の NamingTestsセクションに示されているスキーマを使用して4桁の10進数で名前が付けられます。

今回はおもちゃコマンドなので、思い切ってテストにt9999という名前を付けましょう。 ただし、ファミリとサブコマンドの組み合わせの多くはいっぱいいっぱいであるため、ベストプラクティスは、追加したコマンドに十分近いコマンドを見つけて、その名前付け空間を共有することです。

新しいファイル t/t9999-psuh-tutorial.sh を作成します。 ヘッダーは以下のように始めます(t/README の「WritingTests」および「Source test-lib.sh」参照):

TAP形式の結果を出力するために、テストは test_expect_success 内にフレーム化されます。 git psuh がうまく終了せず、どこかで適切な動物について言及していることを確認しましょう:

あなたのスクリプトの下部に以下を追加して、あなたが必要なすべてを実行したことを示します:

あなたのテストスクリプトを実行可能としてマークしてください:

make -C t test-lint を実行すると、新しいテストスクリプトが正常に作成されたかどうかがわかります。これにより、テスト番号の一意性や実行可能ビットなどがチェックされます。

ローカルで実行してみましょう:

あなたは完全なテストスイートを実行して、 git-push が何も壊さなかったことを確認できます:

では、この変更もコミットしておいてください。

パッチごとの電子メールに加えて、Git コミュニティは、パッチにカバー・レターが付属していることも期待しています。 これは変更提出(change submission)の重要な要素であり、パッチを見るだけではなく、何をしようとしているのか、その理由をコミュニティに高レベルで説明するものです。

カバー・レターのタイトルは、トピック・ブランチ全体の目的を簡潔に網羅するものにする必要があります。 コミット・メッセージのタイトルと同じように、しばしば命令調になっています。 シリーズにタイトルを付ける方法は以下のとおりです:

--- Add the psuh command ---

カバー・レターの本文は、レビュー担当者に追加のコンテキストを提供するために使用されます。 パッチだけでは明らかにならないことは必ず説明してください。 ただし、カバー・レターはコミット履歴に記録されないため、将来リポジトリの履歴を読む人にとって役立つ可能性があるものはコミット・メッセージにも記載する必要があることを忘れないでください。

ここで、 push の本文の例を以下に示します:

ここから、 パッチ・セットをフォーマットしてレビューを受けるための 2 つの異なる方法を示すために、チュートリアルは分岐します。

一番目の方法はGitGitGadgetです。これは、GitHubの一般的なプルリクエストワークフローに既に精通しているユーザーに役立ちます。 この方法ではGitHubアカウントが必要です。

2番目の方法は git send-email にて対応します。これにより、送信する電子メールを少し細かく制御できます。 この方法には、システムに応じて変更される可能性のあるいくつかの設定が必要であり、このチュートリアルでは説明しません。

どちらの方法を選択しても、レビュー担当者との関わりは同じです。 レビュープロセスについては、GitGitGadget と git send-email のセクションの後で説明します。

あなたはGitGitGadgetを使用してレビューするためにパッチを送信する前に、Gitプロジェクトをフォークして変更をアップロードする必要があります。 まず最初に、GitHubアカウントを持っていることを確認してください。

GitHub mirror に移動し、フォークボタン(Fork button)を探します。 あなたの適切と思われる場所にあなたのフォークを配置作成します。

ブランチを自分のフォークにアップロードするには、新しいフォークをリモートとして追加する必要があります。 git remote -v を使用して、すでに追加したリモートを表示できます。 GitHubの新しいフォークのページから、「Clone or download」(クローンまたはダウンロード)を押してURLを取得できます。 次に、以下を実行してリモートを追加し、提供されている例の独自のURLとリモート名を置き換える必要があります:

または、HTTPS URL を使って:

もう一度 git remote -v を実行すると、新しいリモートが表示されます。 プッシュの準備をするために、 git fetch remotename (remotenameの部分はあなたの実際のリモートの名前に置き換えて下さい) とします。

次に、 git branch を実行して、あなたの全ての開発を新しいブランチで行っていることを再確認します。 そうでない場合は、今が新しいコミットを独自のブランチに移動する良い機会です。

このドキュメントの冒頭で簡単に説明したように、作業は master に基づいているため、以下に示すように更新しておくか、好みのワークフローを使用してください。

そして今や、あなたは新しいトピックブランチをプッシュする準備が整いました！ (ブランチ名をあなたの実際のに置き換えるのと、あなたのコマンド名がpushじゃなくてpsuhであることに注意して下さい。)

これで、あなたはGitHubで新しく作成したブランチにアクセスして確認できるようになります。

コードをテストしてレビュー用にフォーマットするには、まず、 gitgitgadget/git に対してプルリクエストを開く必要があります。 https://github.com/gitgitgadget/git にアクセスし、「New pull request」(新しいプルリクエスト)ボタンまたは、新しくプッシュしたブランチの名前とともに表示される便利な「Compare & pull request」(比較してプルリクエスト)ボタンを使用してPRを開きます。

PR のタイトルと説明を確認してください。 GitGitGadget では、あなたの変更の、カバー・レターの件名と本文としてそれぞれ使用されます。 提出物にタイトルを付ける方法と説明に含める内容については、上記 "The cover letter" を参照してください。

満足したら、プル・リクエストを送信します。

あなたがGitGitGadgetを初めて使用する場合(このチュートリアルを使用している可能性が高い)、誰かがツールの使用許可を与える必要があります。 GitGitGadgetのドキュメントに記載されているように、PRに /allow<username> を付けてコメントするにはすでにそれを使用している人が必要です。 GitGitGadgetは、許可が与えられていなくてもCIを介してPRを自動的に実行しますが、誰かがあなたにツールの使用を許可するまで、あなたの変更を /submit することはできません。

CIに失敗した場合は、 git rebase -i を使用して変更を更新し、ブランチを再度プッシュできます:

実際、パッチが next に受け入れられるまで、この方法で変更を続ける必要があります。

あなたのCIを通過し、誰かが /allow コマンドでGitGitGadgetを使用する許可を与えたのなら、レビューのために送信するのは、/submit でPRにコメントするのと同じくらい簡単です。

メーリングリストで受け取るレビューコメントに返信する方法については、 Responding to Reviews に進んでください。

すべてのレビューコメントに従って希望の形でブランチを作成したら、もう一度送信できます:

次に、GitGitGadgetに対するプルリクエストを確認します。 CIが再び開始されたことがわかります。 CIの実行中に、プルリクエストスレッドの上部にある説明を変更するのに適したタイミングです。 カバーレターとして再び使用されます。 この場所を使用して、以前のバージョンから何が変更されたかを説明し、レビュー担当者が何を見ているのかをある程度把握できるようにする必要があります。 CIの実行が完了したら、 /submit でもう一度コメントできます。GitGitGadgetはあなたの変更にv2マークを自動的に追加します。

send-email` の設定はオペレーティングシステムやメールプロバイダーによって異なるので、このチュートリアルでは説明しません。 多くのLinuxディストリビューションでは、 git-send-email は通常の git インストールと一緒にパッケージされていません。 追加パッケージをインストールする必要があるかもしれません。 オンラインには、そのためのリソースがたくさんあります。 また、SMTPサーバーを使用するための正しい設定方法を決定する必要があります。 この設定はシステムやメールの設定によって大きく変わる可能性があるので、このチュートリアルの範囲外です。

Gitを使用したメールの送信は2つの部分からなるプロセスです。 メール自体を準備する前に、パッチを準備する必要があります。 幸いなことに、これは非常に簡単です:

このコマンドは、コミットごとに 1 つのパッチ・ファイルを作成します。 実行した後、お気に入りのテキスト・エディタで各パッチを調べて、すべてが適切に表示されることを確認できます。 ただし、パッチ・ファイルを使用してコードを修正することはお勧めしません。 パッチを変更するよりも、git rebase -i を使用するか、新しいコミットを追加することによって、通常の方法で変更を加える方が良い考えです。

パッチとカバーレターのテンプレートが指定したディレクトリに存在することを確認してください。これであなたがレビューを送信する準備がほぼ整いました！

--cover-letter を指定して format-patch を呼び出したので、カバー・レターのテンプレートは既に用意されています。 それをお気に入りのエディターで開きます。

あなたは既に多数のヘッダーを拝んでいるはずです。 From: ヘッダーが正しいことを確認してください。 その次に、Subject: を変更します(パッチシリーズに適切なタイトルを選ぶには、 上記 を参照してください):

必ず ”[PATCH 0/X]” の部分を保持してください。 これが、このメールがパッチ・シリーズの始まりであることをGitコミュニティに示しており、多くのレビュー担当者がこのタイプのフラグでメールをフィルタリングしています。

あなたはカバーレターを追加するために git send-email を呼び出すときに、いくつかの追加パラメーターを追加する必要があります。

次に、カバーレターの本文を記入する必要があります。 繰り返しますが、含める内容については above を参照してください。

git format-patch --cover-letter によって作成されたテンプレートには、diffstatが含まれています。 これにより、レビュー担当者は、トピックをレビューするときに何をしているのかを要約できます。 サンプル実装から psuh 用に生成されたものは以下のようになります:

最後に、この手紙文にはパッチの生成に使用されたGitのバージョンが含まれます。 この文字列は放っておいても大丈夫です。

この時点で、パッチとカバーレターが入ったディレクトリ psuh/ が作成されているはずです。 あなたがそれを送信する時が来ました！ あなたは以下のように送信できます:

あなたが上記のコマンドを実行すると、各パッチが送信されるたびにインタラクティブなプロンプトが表示されます。 これにより、何かを編集したり送信をやめたりする最後のチャンスが得られます(ただし、繰り返しになりますが、この方法でコードを編集してはいけません)。 これらのプロンプトで y または a を押すと、メールが送信されます！ おめでとうございます！

素晴らしい！これでコミュニティはすべてを捨ててあなたの変更をレビューすることでしょう。 (冗談です、我慢が肝要です)

このセクションでは、あなたのパッチセットの v2 を送信する方法に焦点を当てます。 v2 に何を含める必要があるかについては、 Responding to Reviews にスキップして、レビュー担当者からのコメントの処理方法を確認してください。

v2 の「psuh」トピック ブランチを再利用します。 変更を加える前に、簡単に参照できるように v1 ブランチの先端をマークします:

レビュアーのコメントに基づいてコミットを調整するには、 git rebase -i を使用してパッチ・シリーズを改良します。 パッチ・シリーズを送信する準備ができたら、パッチを再度生成しますが、いくつかの新しいフラグを使用します:

--range-diff master..psuh-v1 パラメータは、カバー・レターに psuh-v1 と psuh の間の範囲差分(range-diff)を含めるように format-patch に指示します (git-range-diff(1) 参照)。 これは、v1 パッチと v2 パッチの違いをレビュアーに伝えるのに役立ちます。

-v2 パラメータは、パッチをバージョン「2」として出力するように format-patch に指示します。 たとえば、v2 パッチはすべて v2-000n-my-commit-subject.patch のような名前になっていることに気付くかもしれません。 -v2 は、[PATCH] の代わりに [PATCH v2] をプレフィックスとしてパッチをフォーマットし、 range-diff は Range-diff against v1 で始まります。

このコマンドを実行すると、 format-patch は v1 パッチと一緒に psuh/ ディレクトリにパッチを出力します。 単一のディレクトリを使用すると、v2 パッチを校正しながら古い v1 パッチを簡単に参照できますが、v2 パッチのみを送信するように注意する必要があります。 psuh/v2-*.patch のようなパターンを使用します (v1 および v2 パッチに一致する psuh/*.patch ではありません)。

カバーレターをもう一度編集します。 何か重要なことがあれば、今が前回のバージョンと現在のバージョンの違いについて言及する良い機会です。 2番目のカバーレターにまったく同じ本文は必要ありません。 レビューアの目に見えない可能性のある変更を説明することに焦点を当てます。

また、あなたはカバーレターのメッセージ ID を見つけなければなりません。 最初のシリーズを送信するときに git send-email の出力をメモしておくができますし、 mailing list で調べることもできます。アーカイブでカバーレターを見つてクリックし、 そして "permalink" または "raw" をクリックすると、 以下のような Message-ID ヘッダーが表示されます:

あなたのメッセージIDは <foo.12345.author@example.com> です。 この文章では以降、この例を使います。 previous cover letter を正しいメッセージIDに置き換えてください。つまり、v2を送信する場合は、v1からのMessage-IDを使用します。 v3を送信する場合は、v2からのMessage-Idを使用します。

メーリングリストではすべてのCCをスレッドに保持するのが一般的であるため、電子メールを見ている間、誰がCCされているかにも注意する必要があります。 これらのCC行は、ヘッダー(件名行の前)に以下のような行を使用して、カバーレターに直接追加できます:

コマンドに渡すメッセージに細心の注意を払いながら、もう一度メールを送信します:

場合によっては、あなたのごくわずかな変更が1つのパッチのみで構成されていることがあります。 その場合、送信する必要があるのは1通のメールだけです。 コミットメッセージはすでに意味があり、パッチの目的(何が起こっているのか、その理由)を高レベルで説明しているはずですが、さらに多くのコンテキストを提供する必要がある場合は、パッチの --- の下で行うことができます。 以下の例を見てください。これは、1回のコミットで git format-patch を使用して生成され、編集されて、 --- とdiffstatの間にコンテンツが追加されています。

うまくいけば、数日後にはあなたのパッチセットへのコメント付きの返信が届くことでしょう。 やったね！ まぁともあれ、これであなたは本来の作業に戻ることができます。

それぞれのコメントには、提案された変更を行ったこと、オリジナルの方が良いと思ったこと、あるいはコメントによって新しい方法を思いついたこと(オリジナルと提案された変更の両方が優れている) をレビュアーに知らせるのが良いマナーです。こうすることで、査読者は、あなたがコメントした事を実装したかどうかを判断するために、あなたのV2を検査する必要がなくなります。

査読者は、提案されたコミットログメッセージまたは変更自体のいずれかで、パッチセットに何を書き込んだかについて質問する場合があります。 応答メッセージでこれらの質問に答える必要がありますが、多くの場合、レビュー担当者が、あなたが何を書くつもりかを理解するためにこれらの質問をした理由は、パッチセットを理解するために説明が必要だったためです。

レビュアーの質問に答えて、レビュアーが「言いたいことがわかった」と言うだけで、満足してはいけないのです。 レビュアーが困っている点を明確にするためにパッチを更新し、v2を準備します。v1でレビュアーからの質問に答えるために使った言葉が、役に立つかもしれません。 あなたの目標は、v2を十分に明確にして、次に読む人に同じ説明をする必要がなくなるようにすることです。

コメントに対して反論する場合は、礼儀正しく、なぜあなたのオリジナルの方が良いと思うのかを説明します。レビュアーがまだあなたに同意しないかもしれないことや、コミュニティの他のメンバーが双方の側に意見するかもしれないことを覚悟してください。他のレビュアーは、あなたとは異なる視点でプロジェクトを見ており、あなたには思いもよらなかったような副作用について考えているかもしれません。なぜその変更が提案されたのか、あるいは査読者があなたに何を求めているのかがわからない場合は、いつでも説明を求めてかまいません。

あなたの電子メールクライアントにプレーンテキストの電子メールモードがあり、オンになっていることを確認してください。 GitメーリングリストはHTMLメールを拒否します。 Maintainer’s Note で概説されているメーリングリストのエチケットにも従ってください。 これは、ボトムポストやインラインリプライに関するほとんどのオープンソースコミュニティのエチケットルールに似ています。

コードに変更を加える場合、 git rebase -i (対話的リベース)を使用すると、最もクリーンになります。つまり、結果のコミットが最も見やすくなります。 O’Reillyの overview ご覧ください。 一般的な考え方は、変更が必要な各コミットを変更することです。 このようにすると、v1では間違いのあるパッチAと、問題なく上流のレビューも必要ないパッチBと、v2ではパッチAを修正したパッチC、を用意する代わりに、正しいパッチAと正しいパッチBでv2を出荷すればいいのです。これは履歴を変更していますが、誰とも共有していないローカル履歴なので、今のところは問題ありません。 (後でこれを行うのは意味がない場合があります。コンテキストについては、次のセクションを参照してください。)

Gitプロジェクトには、 seen と next と master と maint の4つの統合ブランチがあります。 変更は、レビュープロセスの途中で、メンテナによってかなり早い段階で「seen」(表示)されます。 そこから、より広範なテストの準備ができたら、next にマージされます。 多くの初期のテスターは next を使用し、問題を報告する可能性があります。 最終的に、 next を変更すると、通常は安定していると見なされる master になります。 最後に、新しいリリースが出ると、 maint がバグ修正のベースとして使用されます。 このドキュメントの冒頭で述べたように、さまざまな統合ブランチの使用に関する詳細については、「Documents/SubmittingPatches」を参照してください。

話を戻します。 今や、 あなたのコードは上流のレビューアから賞賛されています。 あなたのコードは完璧で、 受け入れられる準備ができています。 他に何もする必要はありません。 メンテナはトピックブランチを next にマージし、最高な気分ですおすし。

しかしながら、この時点以降に完全ではないことにあなたが気付いた場合は、あなたがプロセスのどこにいるかに応じて、いくつかの特別な手順を実行する必要があります。

メンテナが「What’s cooking in git.git」メールで、あなたのトピックに「next」のマークが付けられていることを発表した場合、つまり、トピックを「next」にマージする予定であるが、まだマージしていない場合は、 メンテナにもう少し待つように依頼するメールを送るべきです: 「シリーズのv4を送信し、 next のマークを付けましたが、これを変更する必要があります。v5を待ってからマージしてください。」

トピックがすでに next にマージされている場合は、git rebase -i でパッチを修正するのではなく、インクリメンタルに、つまり https://github.com/gitster/git にあるようにメンテナのトピックブランチを基点として別のコミットで変更を加えてください。 あなたの仕事はまだ同じトピックにありますが、トピックブランチの大規模な書き直しではなく、インクリメンタルになっています。

メンテナのGitHubのトピックブランチはGitGitGadgetにミラーリングされているため、レビューをそのように送信する場合は、適切なGitGitGadget/Gitブランチに対してPRを開く必要があります。

git send-email を使用している場合は、以前と同じように使用できますが、 <topic>..<mybranch> からdiffを生成し、 master の代わりに <topic> に基づいて作業する必要があります。