English ▾ トピック ▾ 最新バージョン ▾ MyFirstContribution は 2.50.0 で最終更新されました

この情報は Git プロジェクトに固有のものです

この情報は、Git プロジェクト自体に貢献する予定がある場合にのみ関連することにご注意ください。通常の Git ユーザーにとって必読ではありません。

概要

これは、Git ツリーに変更を作成し、レビューのために送信し、コメントに基づいて変更を行うエンドツーエンドのワークフローを示すチュートリアルです。

前提条件

このチュートリアルは、Git を使用してソースコードを管理することに既に慣れていることを前提としています。Git ワークフローのステップについては、ほとんど説明しません。

このチュートリアルは以下のドキュメントを要約することを目的としていますが、読者は追加のコンテキストを見つけると役立つかもしれません

  • Documentation/SubmittingPatches

  • Documentation/howto/new-command.adoc

ヘルプの取得

行き詰まった場合は、以下の場所でヘルプを求めることができます。

git@vger.kernel.org

これは、コードレビュー、バージョンアナウンス、設計に関する議論などが行われる主要な Git プロジェクトメーリングリストです。貢献に興味のある方は、ここで質問を投稿することを歓迎します。Git リストはプレーンテキストのみのメールを要求し、メールに返信する際にはインラインとボトムポストを好みます。あなたへのすべての返信で CC されます。オプションで、<git+subscribe@vger.kernel.org> にメールを送信することでリストを購読できます (詳細はhttps://subspace.kernel.org/subscribing.html を参照)。このメーリングリストのアーカイブはブラウザで閲覧できます。

Libera Chat の #git-devel

この IRC チャンネルは、Git 貢献者間の会話用です。誰かが現在オンラインであなたの質問への答えを知っていれば、リアルタイムでヘルプを受けることができます。そうでなければ、スクロールバックを読んで、誰かがあなたに答えたかどうかを確認できます。IRC はオフラインのプライベートメッセージを許可しないため、誰かにプライベートメッセージを送信してから IRC からログアウトすると、彼らはあなたに返信できません。チャンネルで質問する方が、切断した場合でも回答を得られ、他の人も会話から学ぶことができるので良いでしょう。

始める

Git リポジトリをクローンする

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

$ git clone https://github.com/git/git git
$ cd git

依存関係のインストール

Git をソースからビルドするには、いくつかの依存関係をシステムにインストールする必要があります。何が必要かのヒントについては、INSTALL を参照し、Git の外部プログラムとライブラリへの依存関係に関するセクションに特に注意してください。そのドキュメントでは、新しくビルドした Git をインストールせずに「テストドライブ」する方法が言及されています。それがこのチュートリアルで使用する方法です。

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

$ make
注
 Git のビルドは並列化可能です。-j# は上記には含まれていませんが、ここでも他の場所でも、お好みで使用できます。

解決すべき問題の特定

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

（この分野では、sl のような人気のあるコマンドの実装で他の取り組みも見てきました。）

ワークスペースのセットアップ

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

このドキュメントの目的のために、すべての作業をアップストリームプロジェクトの master ブランチをベースにします。開発に使用する psuh ブランチを次のように作成します。

$ git checkout -b psuh origin/master

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

コーディング開始！

注
 リファレンス実装は https://github.com/nasamuffin/git/tree/psuh で見つけることができます。

新しいコマンドの追加

多くのサブコマンドは組み込み (builtin) として書かれており、C で実装され、メインの git 実行可能ファイルにコンパイルされます。非常にシンプルな psuh コマンドを組み込みとして実装することで、コードベースの構造、内部 API、および貢献者としてレビューアやメンテナと協力してこの変更をシステムに統合するプロセスをデモンストレーションします。

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

int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
	     const char *prefix UNUSED, struct repository *repo UNUSED)

いくつか注意すべき点

  • サブコマンドの実装は、main() と同様に、コマンドライン引数を int argc + const char **argv で受け取ります。

  • さらに、prefix と repo の2つの追加パラメータを受け取ります。これらが何を意味するかは、ずっと後になるまで説明されません。

  • この最初の例ではパラメータを使用しないため、コンパイラは未使用のパラメータについて警告を発します。これら4つのパラメータのリストは、新しい組み込みコマンドを追加するためのAPIによって義務付けられているため、省略することはできません。代わりに、それぞれに UNUSED を追加して、使用していないことを**知っている**ことをコンパイラに伝えます。

psuh の宣言も追加する必要があります。 builtin.h を開き、cmd_pull の宣言を見つけて、その直前に psuh の新しい行を追加して、宣言をアルファベット順にソートしておきます。

int cmd_psuh(int argc, const char **argv, const char *prefix, struct repository *repo);

あなたの psuh.c に #include "builtin.h" を含めるようにしてください。また、出力テキストの表示に関連する関数を使用するために #include "gettext.h" も含める必要があります。

cmd_psuh 関数に一時的な printf を追加します。これでビルドルールを追加してコマンドを登録できるので、これが良い出発点となります。

注
 一時的なテキストだけでなく、このチュートリアルの過程で追加するテキストの多くはユーザー向けです。つまり、ローカライズ可能である必要があります。po/README の「翻訳用の文字列をマークする」セクションを参照してください。チュートリアル全体を通して、必要に応じて翻訳用の文字列をマークします。将来ユーザー向けのコマンドを作成する際にも、そうする必要があります。 
int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
	     const char *prefix UNUSED, struct repository *repo UNUSED)
{
	printf(_("Pony saying hello goes here.\n"));
	return 0;
}

ビルドしてみましょう。Makefile を開き、builtin/pull.o が BUILTIN_OBJS に追加されている箇所を見つけ、同じようにアルファベット順で隣に builtin/psuh.o を追加します。完了したら、トップレベルディレクトリに移動し、単に make でビルドします。また、追加の警告をオンにするために DEVELOPER=1 変数も追加します。

$ echo DEVELOPER=1 >config.mak
$ make
注
 Git プロジェクトを開発する際には、DEVELOPER フラグを使用することが推奨されます。もしそれがあなたにとって機能しない理由がある場合、オフにすることはできますが、その問題をメーリングリストに報告するのは良い考えです。

素晴らしい、これで新しいコマンドが単独でうまくビルドされます。しかし、誰もそれを呼び出しません。それを変更しましょう。

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

オプションは builtin.h の「新しい組み込み機能の追加」の下に文書化されています。後でユーザーの現在のワークスペースコンテキストに関するデータを印刷することを期待しているため、Git ディレクトリが必要なので、唯一のオプションとして RUN_SETUP を選択します。

続けて、もう一度ビルドします。クリーンなビルドが表示されるはずなので、動作するかどうか確認してみましょう。bin-wrappers ディレクトリには、テストに使用できるバイナリがあります。

$ ./bin-wrappers/git psuh

見てください！コマンドができました！よくできました！コミットしましょう。

git status を実行すると、Makefile, builtin.h, git.c が変更され、builtin/psuh.c と git-psuh が追跡対象外になっていることがわかります。まず、無視すべきバイナリに対処しましょう。エディタで .gitignore を開き、/git-pull を見つけて、新しいコマンドのエントリをアルファベット順で追加します。

...
/git-prune-packed
/git-psuh
/git-pull
/git-push
/git-quiltimport
/git-range-diff
...

もう一度 git status を確認すると、git-psuh が追跡対象外のリストから削除され、.gitignore が変更されたリストに追加されているはずです。これでステージングしてコミットできます。

$ git add Makefile builtin.h builtin/psuh.c git.c .gitignore
$ git commit -s

コミットメッセージを記述するためにエディタが表示されます。コミットは、作業中のコンポーネント名を含む50列以下の件名行で開始し、その後は空白行（常に必須）とコミットメッセージの本文を記述します。本文では、主要なコンテキストを提供する必要があります。明示的であることを忘れず、変更の「なぜ」を提供してください。特に、差分から簡単に理解できない場合は重要です。コミットメッセージを編集する際、上記の -s によって追加された Signed-off-by トレーラーを削除しないでください。

psuh: add a built-in by popular demand

Internal metrics indicate this is a command many users expect to be
present. So here's an implementation to help drive customer
satisfaction and engagement: a pony which doubtfully greets the user,
or, a Pony Saying "Um, Hello" (PSUH).

This commit message is intentionally formatted to 72 columns per line,
starts with a single line as "commit message subject" that is written as
if to command the codebase to do something (add this, teach a command
that). The body of the message is designed to add information about the
commit that is not readily deduced from reading the associated diff,
such as answering the question "why?".

Signed-off-by: A U Thor <author@example.com>

続けて、git show で新しいコミットを検査してください。「psuh:」は、主に psuh コマンドを変更したことを示します。件名行は、読者に何を変更したかを示します。サインオフ行 (-s) は、あなたが Developer’s Certificate of Origin 1.1 に同意したことを示します (詳細は Documentation/SubmittingPatches [[dco]] ヘッダーを参照)。

チュートリアルの残りの部分では、簡潔さのために件名行のみが記載されます。ただし、このドキュメントの冒頭でリンクされているリファレンス実装には、完全に記述されたコミットメッセージの例が用意されています。

実装

文字列を出力するだけでなく、少なくとも何かを行うことはおそらく役立ちます。まず、取得するすべてのものを見てみましょう。

渡された引数をダンプするように cmd_psuh の実装を変更し、既存の printf() 呼び出しはそのままにします。引数が使用されるようになったため、UNUSED マクロを削除します。

	int i;

	...

	printf(Q_("Your args (there is %d):\n",
		  "Your args (there are %d):\n",
		  argc),
	       argc);
	for (i = 0; i < argc; i++)
		printf("%d: %s\n", i, argv[i]);

	printf(_("Your current working directory:\n<top-level>%s%s\n"),
	       prefix ? "/" : "", prefix ? prefix : "");

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

#include "config.h" と #include "repository.h" を追加してください。そして、関数本体に以下のコードを追加してください。

	const char *cfg_name;

...

	repo_config(repo, git_default_config, NULL);
	if (repo_config_get_string_tmp(repo, "user.name", &cfg_name))
		printf(_("No name is found in config\n"));
	else
		printf(_("Your name: %s\n"), cfg_name);

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

表示される名前が、実行したときに表示される名前と一致していることを確認する必要があります。

$ git config --get user.name

素晴らしい！これで Git 設定で値を確認する方法がわかりました。進捗状況を失わないように、これもコミットしましょう。

$ git add builtin/psuh.c
$ git commit -sm "psuh: show parameters & config opts"
注
 繰り返しになりますが、上記はこのチュートリアルを簡潔にするためです。実際の変更では -m を使用せず、エディタを使用して意味のあるメッセージを作成してください。

それでも、ユーザーの作業コンテキストがどのようなものかを知ることができると良いでしょう。ユーザーの現在のブランチ名を表示できるか見てみましょう。git status の実装を模倣できます。プリンタは wt-status.c にあり、ブランチが struct wt_status に保持されていることがわかります。

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

status_init_config(&s, git_status_config);

しかし、さらに掘り下げていくと、status_init_config() が repo_config() の呼び出しをラップしていることがわかります。前のコミットで記述したコードを変更しましょう。

struct wt_status を使用できるように、ヘッダーを含めるようにしてください。

#include "wt-status.h"

次に、cmd_psuh の実装を変更して、struct wt_status を宣言し、準備し、その内容を出力するようにします。

	struct wt_status status;

...

	wt_status_prepare(repo, &status);
	repo_config(repo, git_default_config, &status);

...

	printf(_("Your current branch: %s\n"), status.branch);

もう一度実行してください。見てください - これが現在のブランチの (詳細な) 名前です！

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

$ git add builtin/psuh.c
$ git commit -sm "psuh: print the current branch"

次に、特定のコミットに関する情報を取得できるかどうか見てみましょう。

幸いなことに、ここにはいくつかのヘルパーがあります。commit.h には、ハードコードされた文字列を渡すだけで済む lookup_commit_reference_by_name という関数があります。pretty.h には、完全なフォーマットオブジェクトを渡す必要のない非常に便利な pp_commit_easy() 呼び出しがあります。

以下のインクルードを追加します。

#include "commit.h"
#include "pretty.h"

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

	struct commit *c = NULL;
	struct strbuf commitline = STRBUF_INIT;

...

	c = lookup_commit_reference_by_name("origin/master");

	if (c != NULL) {
		pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline);
		printf(_("Current commit: %s\n"), commitline.buf);
	}

struct strbuf は、基本的な char* にいくつかの安全装置を提供します。その1つが、バッファオーバーランを防ぐための長さメンバです。STRBUF_INIT で適切に初期化する必要があります。char* を渡す必要があるときに覚えておいてください。

lookup_commit_reference_by_name は渡された名前を解決するため、そこで値をいじって、どのような種類のものが得られるかを確認できます。

pp_commit_easy は pretty.h の便利なラッパーで、完全なフォーマット構造体ではなく、単一のフォーマット列挙型の省略形を受け取ります。そして、その省略形に従ってコミットをきれいに表示します。これらは、多くの Git コマンドで --pretty=FOO で利用できるフォーマットに似ています。

ビルドして実行し、例と同じ名前を使用している場合は、認識している origin/master の最新コミットの件名行が表示されるはずです。素晴らしいですね！これもコミットしましょう。

$ git add builtin/psuh.c
$ git commit -sm "psuh: display the top of origin/master"

ドキュメントの追加

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

$ ./bin-wrappers/git help psuh

新しいコマンドは文書化されていません！これを修正しましょう。

Documentation/git-*.adoc を見てください。これらは Git が認識しているサブコマンドのマニュアルページです。これらを開いてフォーマットに慣れてから、新しいファイル Documentation/git-psuh.adoc を作成してください。Git プロジェクトのほとんどのドキュメントと同様に、ヘルプページは AsciiDoc で記述されています (CodingGuidelines の「Writing Documentation」セクションを参照)。以下のテンプレートを使用して、独自のマニュアルページを作成してください。

git-psuh(1)
===========

NAME
----
git-psuh - Delight users' typo with a shy horse


SYNOPSIS
--------
[verse]
'git-psuh [<arg>...]'

DESCRIPTION
-----------
...

OPTIONS[[OPTIONS]]
------------------
...

OUTPUT
------
...

GIT
---
Part of the git[1] suite

これの中で最も重要な部分は、=で下線が引かれたファイルヘッダー、NAMEセクション、そして通常コマンドが引数を受け取る場合の文法を含むSYNOPSISです。あなたのドキュメントが他のGitやUNIXのマニュアルページと一貫性があるように、よく確立されたマニュアルページヘッダーを使用するようにしてください。これは、必要な情報が含まれていると知っているセクションにスキップできるユーザーにとって、作業を容易にします。

注
 ドキュメントをビルドする前に、asciidoc パッケージがインストールされていることを確認してください。

マニュアルページを記述したので、明示的にビルドする必要があります。AsciiDoc を man が読める troff に変換します。

$ make all doc
$ man Documentation/git-psuh.1

または

$ make -C Documentation/ git-psuh.1
$ man Documentation/git-psuh.1

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

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

続けて、新しいドキュメントの変更をコミットしてください。

使用方法のテキストの追加

./bin-wrappers/git psuh -h を実行してみてください。コマンドは最後にクラッシュするはずです。これは、-h が特別なケースであり、コマンドが使用方法を印刷することで処理する必要があるためです。

Documentation/technical/api-parse-options.adoc を見てください。これは、処理する必要があるオプションを抽出し、使用文字列を受け取る便利なツールです。

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

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

グローバルスコープで、使用文字列の配列を追加します。

static const char * const psuh_usage[] = {
	N_("git psuh [<arg>...]"),
	NULL,
};

次に、cmd_psuh() の実装内で、option 構造体を宣言し、設定できます。私たちのものはかなり地味ですが、parse_options() をより詳しく探求したい場合は、さらに追加できます。

	struct option options[] = {
		OPT_END()
	};

最後に、引数とプレフィックスを印刷する前に、parse-options() の呼び出しを追加します。

	argc = parse_options(argc, argv, prefix, options, psuh_usage, 0);

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

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

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

git-prune-packed                        plumbingmanipulators
git-psuh                                mainporcelain		info
git-pull                                mainporcelain           remote
git-push                                mainporcelain           remote

もう一度ビルドしてください。これで、-h を付けて実行すると、使用方法が表示され、他の興味深いことが起こる前にコマンドが終了するはずです。素晴らしい！

これもコミットしてください。

テスト

あなたのコードをテストすることは重要です。このような小さなおもちゃのコマンドであってもです。さらに、あなたのパッチはテストなしでは Git ツリーに受け入れられません。あなたのテストは次のことを行うべきです。

  • 機能の現在の動作を示す

  • 現在の動作が期待される動作と一致することを証明する

  • 外部から見える動作が後の変更で壊れないことを保証する

では、いくつかのテストを書きましょう。

関連資料：t/README

テスト構造の概要

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

新しいテストの作成

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

新しいファイル t/t9999-psuh-tutorial.sh を作成します。ヘッダーを次のように記述します (詳細は t/README の「Writing Tests」と「Source test-lib.sh」を参照)。

#!/bin/sh

test_description='git-psuh test

This test runs git-psuh and makes sure it does not crash.'

. ./test-lib.sh

テストは TAP 形式の結果を出力するために test_expect_success の中にフレームされます。git psuh がうまく終了し、どこかに正しい動物の名前が記載されていることを確認しましょう。

test_expect_success 'runs correctly with no args and good output' '
	git psuh >actual &&
	grep Pony actual
'

スクリプトの最後に以下を追加して、意図したすべてを実行したことを示します。

test_done

テストスクリプトを実行可能にマークしてください。

$ chmod +x t/t9999-psuh-tutorial.sh

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

ローカルでの実行

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

$ make
$ cd t/ && prove t9999-psuh-tutorial.sh

完全なテストスイートを実行し、git-psuh が何も壊していないことを確認できます。

$ cd t/
$ prove -j$(nproc) --shuffle t[0-9]*.sh
注
 make test でも同様に実行できますし、TAP に対応したテストハーネスも利用できます。prove は並行して実行できます。shuffle はテストの実行順序をランダム化し、不要なテスト間の依存関係に対して堅牢にします。prove は出力もより見やすくします。

これもコミットしてください。

共有準備：パッチシリーズの構造

Git プロジェクトでは、コードレビューがメールによるパッチを通じて行われ、コミュニティによって準備され承認されると、メンテナによって適用されることに既にお気づきかもしれません。Git プロジェクトはプルリクエストからの貢献を受け付けておらず、レビューのために送信されるパッチは特定の形式でフォーマットする必要があります。

コミットをメールパッチに変換する方法を見る前に、最終結果である「パッチシリーズ」がどのようなものか分析しましょう。以下は、Git メーリングリストアーカイブのウェブインターフェースでパッチシリーズの概要表示の例です。

2022-02-18 18:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget
2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget
2022-02-18 19:10   ` Ævar Arnfjörð Bjarmason [this message]
2022-02-18 19:39     ` Taylor Blau
2022-02-18 19:48       ` Ævar Arnfjörð Bjarmason
2022-02-18 19:35   ` Taylor Blau
2022-02-21  1:43     ` John Cai
2022-02-21  1:50       ` Taylor Blau
2022-02-23 19:50         ` John Cai
2022-02-18 20:00   ` // other replies elided
2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget
2022-02-18 19:15   ` Ævar Arnfjörð Bjarmason
2022-02-18 20:26     ` Junio C Hamano
2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget
2022-02-18 19:20   ` Ævar Arnfjörð Bjarmason
2022-02-19  0:21     ` Taylor Blau
2022-02-22  2:36     ` John Cai
2022-02-22 10:51       ` Ævar Arnfjörð Bjarmason
2022-02-18 19:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason
2022-02-22 18:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget
2022-02-22 18:30   ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget
2022-02-23  8:54     ` Ævar Arnfjörð Bjarmason
2022-02-23 21:27       ` Junio C Hamano
// continued

いくつか注意点があります。

  • 各コミットは個別のメールとして送信され、コミットメッセージのタイトルが件名となり、n 個のコミットシリーズの i 番目のコミットには "[PATCH i/n]" がプレフィックスとして付きます。

  • 各パッチは、シリーズの「カバーレター」と呼ばれる紹介メールへの返信として送信され、「[PATCH 0/n]」というプレフィックスが付きます。

  • パッチシリーズのその後の反復は、「PATCH」の代わりに「PATCH v2」、「PATCH v3」などとラベル付けされます。例えば、「[PATCH v2 1/3]」は2回目の反復の3つのパッチのうちの最初のパッチになります。各反復は新しいカバーレター（上記のように「[PATCH v2 0/3]」など）とともに送信され、そのカバーレター自体が以前の反復のカバーレターへの返信となります（これについては後述します）。

注
 単一パッチのトピックは、「[PATCH]」、「[PATCH v2]」などで、_i_/_n_ の番号付けなしで送信されます（ただし、上記の議論の概要には単一パッチのトピックは表示されていません）。

カバーレター

Git コミュニティでは、パッチごとにメールを送信するだけでなく、カバーレターを添付することも期待されています。これは変更提出の重要な要素であり、コミュニティに対して、あなたのパッチを見るだけではわかりにくい、あなたが何をしようとしているのか、そしてなぜそうするのかを高いレベルで説明します。

あなたのカバーレターのタイトルは、トピックブランチ全体の目的を簡潔に表すものでなければなりません。多くの場合、コミットメッセージのタイトルと同様に、命令形です。これがシリーズのタイトルです。

psuh コマンドを追加 ---

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

以下は psuh の本文の例です。

Our internal metrics indicate widespread interest in the command
git-psuh - that is, many users are trying to use it, but finding it is
unavailable, using some unknown workaround instead.

The following handful of patches add the psuh command and implement some
handy features on top of it.

This patchset is part of the MyFirstContribution tutorial and should not
be merged.

ここでチュートリアルは分岐し、パッチセットをフォーマットしてレビューしてもらうための2つの異なる方法をデモンストレーションします。

最初に説明する方法は GitGitGadget です。これは、GitHub の一般的なプルリクエストワークフローに既に慣れている人にとって役立ちます。この方法には GitHub アカウントが必要です。

2番目に説明する方法は git send-email です。これは、送信するメールをより細かく制御できます。この方法には、システムによって異なるセットアップが必要であり、このチュートリアルでは説明しません。

どちらの方法を選択しても、レビューアとのやり取りは同じです。レビュープロセスは、GitGitGadget と git send-email のセクションの後に説明されます。

GitGitGadget を介したパッチの送信

パッチを送信する1つのオプションは、典型的なプルリクエストワークフローに従い、GitGitGadget を介してパッチを送信することです。GitGitGadget は、ヨハネス・シンデリンによって作成されたツールで、GitHub の PR ワークフローに慣れている人にとって、Git 貢献者としての生活を容易にします。これにより、貢献者は Git プロジェクトのミラーに対してプルリクエストを開くことができ、PR をメールのセットに変換して送信する魔法のような処理を行います。また、Git の継続的インテグレーションスイートも実行してくれます。詳細は https://gitgitgadget.github.io/ で文書化されています。

GitHub で git/git をフォークする

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

GitHub ミラーにアクセスし、「Fork」ボタンを探します。フォークを適切な場所に配置して作成します。

自身のフォークへのアップロード

ブランチを自身のフォークにアップロードするには、新しいフォークをリモートとして追加する必要があります。git remote -v を使用して、既に追加されているリモートを表示できます。GitHub の新しいフォークのページから、「Clone or download」を押して URL を取得します。その後、以下のコマンドを実行して追加します。提供された例の代わりに、自身の URL とリモート名を使用してください。

$ git remote add remotename git@github.com:remotename/git.git

または HTTPS URL を使用する

$ git remote add remotename https://github.com/remotename/git/.git

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

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

このドキュメントの冒頭で簡単に述べたように、私たちの作業は master をベースにしているため、以下の通り、またはあなたの好みのワークフローを使用して更新してください。

$ git checkout master
$ git pull -r
$ git rebase master psuh

最後に、新しいトピックブランチをプッシュする準備ができました！(ブランチとコマンド名の選択のため、以下のコマンドを入力する際には注意してください。)

$ git push remotename psuh

これで、GitHub で新しく作成したブランチをチェックアウトできるはずです。

GitGitGadget への PR の送信

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

PR のタイトルと説明を確認してください。これらはそれぞれ、GitGitGadget によって変更のカバーレターの件名と本文として使用されます。提出物のタイトルの付け方と説明に含める内容については、上記の「カバーレター」を参照してください。

注
 単一パッチの貢献の場合、コミットメッセージはすでに意味を持ち、パッチの目的 (何が起こっているのか、そしてなぜなのか) を高いレベルで説明しているはずなので、通常は追加のコンテキストは必要ありません。その場合、GitHub がコミットメッセージから自動的に生成する PR 説明を削除してください (PR 説明は空であるべきです)。もしさらにコンテキストを提供する必要がある場合は、そのスペースで提供することができ、GitGitGadget が送信するメールに、3つのダッシュの行と diffstat の間に追記されます (ボーナスチャプター: 単一パッチの変更 で送信後の表示を確認できます)。

問題がなければ、プルリクエストを送信してください。

CI の実行と送信準備

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

注
 /allow を付与できる人は、通常、最近のプルリクエストで誰かが /allow を付与されているかどうかを調べることで見つけることができます (検索: is:pr is:open "/allow")。この場合、作成者と /allow を付与した人の両方があなたに /allow を付与できます。または、Libera Chat の #git-devel IRC チャンネルでプルリクエストをリンクして、誰かに /allow を依頼することで見つけることもできます。

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

$ git push -f remotename psuh

実際、あなたのパッチが next に受け入れられるまで、この方法で変更を加え続けるべきです。

パッチの送信

CI がパスし、誰かが /allow コマンドで GitGitGadget を使用する許可を与えてくれたので、PR に /submit とコメントするだけでレビューのために送信できます。

コメントで更新

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

すべてのレビューコメントに従ってブランチを望む形に戻したら、もう一度提出できます。

$ git push -f remotename psuh

次に、GitGitGadget に対するプルリクエストを見てください。CI が再び開始されているはずです。CI が実行されている間に、プルリクエストスレッドの冒頭にある説明を変更するのに良いタイミングです。これは再びカバーレターとして使用されます。このスペースを使用して、前回のバージョンから何が変わったのかを説明し、レビュー担当者が何を見ているのかを理解できるようにする必要があります。CI の実行が完了したら、もう一度 /submit とコメントできます。GitGitGadget は自動的に変更に v2 マークを追加します。

git send-email でパッチを送信する

GitGitGadget を使いたくない場合は、Git 自身を使ってパッチをメールで送ることもできます。この方法で Git を使う利点には、件名行のよりきめ細かい制御 (例えば、件名に [RFC PATCH] タグを使用できること) や、「ドライラン」メールを自分に送って、リストに送る前にすべてがうまくいくことを確認できることなどがあります。

前提条件: git send-email のセットアップ

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

初期パッチセットの準備

Git でメールを送信するのは2段階のプロセスです。メール自体を準備する前に、パッチを準備する必要があります。幸い、これは非常に簡単です。

$ git format-patch --cover-letter -o psuh/ --base=auto psuh@{u}..psuh

  1. --cover-letter オプションは、format-patch にカバーレターのテンプレートを作成するよう指示します。送信する前にテンプレートに入力する必要がありますが、今のところ、テンプレートは他のパッチの隣にあります。

  2. -o psuh/ オプションは、format-patch にパッチファイルをディレクトリに配置するよう指示します。これは、git send-email がディレクトリを受け取り、そこからすべてのパッチを送信できるため便利です。

  3. --base=auto オプションは、受信者がパッチシリーズを適用することを期待される「ベースコミット」を記録するようにコマンドに指示します。auto 値は、format-patch がリモートトラッキングブランチの先端コミットと指定されたリビジョン範囲の共通マージベースであるベースコミットを自動的に計算するようにします。

  4. psuh@{u}..psuh オプションは、format-patch に、psuh ブランチがそのアップストリームから分岐して以来 (「ワークスペースのセットアップ」セクションの例に従った場合、origin/master です)、psuh ブランチで作成したコミットのパッチを生成するよう指示します。psuh ブランチに既にいる場合は、単に「現在のブランチがアップストリームから分岐して以来のコミット」を意味する @{u} と言うことができます。これは同じことです。

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

注
 オプションとして、--rfc フラグを使用して、パッチの件名に「[PATCH]」の代わりに「[RFC PATCH]」というプレフィックスを付けることもできます。RFC は「request for comments (コメントを求める)」の略で、コードはまだ提出準備が整っていないが、コードレビュープロセスを開始したいことを示します。これは、パッチが提案であるものの、コミュニティがそのアプローチで問題を解決したいかどうか確信が持てない場合にも使用できます。一種の設計レビューを行うためです。リストには「WIP」とマークされたパッチも表示されることがあります。これは未完成だが、レビュー担当者にこれまでの内容を見てもらいたいという意味です。このフラグは --subject-prefix=WIP で追加できます。

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

メールの準備

format-patch を --cover-letter で呼び出したので、カバーレターテンプレートはすでに準備されています。お好みのエディタで開いてください。

すでにいくつかのヘッダーが存在するはずです。From: ヘッダーが正しいか確認してください。次に、Subject: を修正します (パッチシリーズの良いタイトルの選び方については上記を参照)。

Subject: [PATCH 0/7] Add the 'psuh' command

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

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

次に、カバーレターの本文を記述する必要があります。繰り返しになりますが、含めるコンテンツについては上記を参照してください。

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

 Documentation/git-psuh.adoc | 40 +++++++++++++++++++++
 Makefile                    |  1 +
 builtin.h                   |  1 +
 builtin/psuh.c              | 73 ++++++++++++++++++++++++++++++++++++++
 git.c                       |  1 +
 t/t9999-psuh-tutorial.sh    | 12 +++++++
 6 files changed, 128 insertions(+)
 create mode 100644 Documentation/git-psuh.adoc
 create mode 100644 builtin/psuh.c
 create mode 100755 t/t9999-psuh-tutorial.sh

最後に、レターにはパッチの生成に使用された Git のバージョンが含まれます。その文字列はそのままにしておいてください。

メールの送信

この時点で、パッチとカバーレターで満たされた psuh/ ディレクトリがあるはずです。メールを送信する時が来ました！次のように送信できます。

$ git send-email --to=target@example.com psuh/*.patch
注
 返信先アドレスの変更や、CC、BCC 行の追加など、役立つ可能性のある他のオプションについては、git help send-email を確認してください。
注
 誰を CC に含めるべきか不明な場合、contrib/contacts/git-contacts を実行すると、潜在的なレビュー担当者のリストを表示できます。さらに、git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch[1] を実行すると、このメールアドレスリストが自動的に send-email に渡されます。
注
 実際のパッチを送信する場合は git@vger.kernel.org に送られますが、チュートリアルからのパッチセットを実際のメーリングリストには送らないでください！今は、それがどのように見えるかを確認するために、自分自身に送信してください。

上記のコマンドを実行すると、送信されようとしている各パッチに対して対話型のプロンプトが表示されます。これにより、最後に編集したり、送信を中止したりする機会が与えられます (ただし、この方法でコードを編集しないでください)。これらのプロンプトで y または a を押すと、メールが送信されます！おめでとうございます！

素晴らしい、これでコミュニティはすべてを捨ててあなたの変更をレビューします。（冗談です、辛抱強く待ちましょう！）

v2 の送信

このセクションでは、パッチセットの v2 を送信する方法に焦点を当てます。v2 に何を含めるべきかを学ぶには、レビュー担当者からのコメントへの対応方法については、レビューへの対応に進んでください。

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

$ git checkout psuh
$ git branch psuh-v1

レビュー担当者のコメントに基づいてコミットを調整するために、git rebase -i を使用してパッチシリーズを洗練します。パッチシリーズを提出する準備ができたら、新しいフラグを使用して再度パッチを生成します。

$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..

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

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

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

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

また、以前のカバーレターの Message-ID を見つける必要があります。git send-email の出力から最初のシリーズを送信するときにメモするか、メーリングリストで検索することができます。アーカイブであなたのカバーレターを見つけ、それをクリックし、「Permalink」または「Raw」をクリックして Message-ID ヘッダーを表示します。それは一致するはずです。

Message-ID: <foo.12345.author@example.com>

あなたの Message-ID は <foo.12345.author@example.com> です。この例は以下でも使用されます。必ず、あなたの**以前のカバーレター**の正しい Message-ID に置き換えてください。つまり、v2 を送信する場合は v1 の Message-ID を、v3 を送信する場合は v2 の Message-ID を使用してください。

メールを見ている間に、CC に誰が含まれているかにも注意してください。メーリングリストでは、スレッドのすべての CC を保持するのが一般的な慣行だからです。これらの CC 行は、ヘッダーに (Subject 行の前に) 次のように記述することで、カバーレターに直接追加できます。

CC: author@example.com, Othe R <other@example.com>

再度メールを送信してください。その際、コマンドにどのメッセージを渡すかに注意してください。

$ git send-email --to=target@example.com
		 --in-reply-to="<foo.12345.author@example.com>"
		 psuh/v2-*.patch

ボーナスチャプター：単一パッチの変更

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

From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001
From: A U Thor <author@example.com>
Date: Thu, 18 Apr 2019 15:11:02 -0700
Subject: [PATCH] README: change the grammar

I think it looks better this way. This part of the commit message will
end up in the commit-log.

Signed-off-by: A U Thor <author@example.com>
---
Let's have a wild discussion about grammar on the mailing list. This
part of my email will never end up in the commit log. Here is where I
can add additional context to the mailing list about my intent, outside
of the context of the commit log. This section was added after `git
format-patch` was run, by editing the patch file in a text editor.

 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 88f126184c..38da593a60 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 Git - fast, scalable, distributed revision control system
 =========================================================

-Git is a fast, scalable, distributed revision control system with an
+Git is a fast, scalable, and distributed revision control system with an
 unusually rich command set that provides both high-level operations
 and full access to internals.

--
2.21.0.392.gf8f6787159e-goog

パッチがメールで送られた - 次は何？

更新されたバージョンを送信する前に、レビュー担当者が最初のパッチを処理するのに十分な時間を与えてください。つまり、すぐに新しいバージョンを送信したいという誘惑に抵抗してください。なぜなら、他の人はすでに最初のバージョンをレビューし始めているかもしれないからです。

レビューコメントを待っている間に、最初のパッチに間違いを見つけたり、パッチの目的を達成するための別のより良い方法に気づくかもしれません。この場合、以下のように他のレビュー担当者にあなたの発見を伝えることができます。

  • 見つかった間違いが軽微な場合は、レビュー担当者のふりをしてパッチに返信し、更新されたバージョンで修正することを言及してください。

  • 一方、方向性を大きく変えたいと思い、最初のパッチのレビューが（関係者全員にとって）時間の無駄になると考える場合は、すぐに「より良いアプローチに取り組んでいるので、このパッチは無視して更新版を待ってください。」のような返信でパッチを撤回してください。

上記は、最初のパッチを未完成のまま早めに送信してしまった場合の良い慣行です。しかし、もちろん、そもそもパッチを早めに送信するのを避けるのがより良いアプローチです。

レビュー担当者がパッチの新しいバージョンをそれぞれ検討するのに必要な時間を考慮してください。今すぐ最初のバージョンを見て（その後、2日間で「おっと、このバージョンは以前のバージョンよりも好きだ」というパッチがいくつか続く）、レビュー担当者は、2日後に1つの洗練されたバージョンが届き、そのバージョンに間違いが少なく、レビューする必要があるのはそのバージョンだけであることを強く望みます。

レビューへの対応

数日後、あなたのパッチセットにいくつかのコメントが付いた返信を受け取れることを願っています。やった！これでまた作業に戻れますね。

各コメントに返信し、提案された変更を行ったこと、元のほうが良いと感じていること、またはコメントが元の変更と提案された変更の両方よりも優れた新しい方法を行うきっかけになったことをレビュー担当者に通知するのが良いマナーです。これにより、レビュー担当者はあなたが彼らのコメントを実装したかどうかを確認するためにv2を検査する必要がなくなります。

レビュー担当者は、あなたがパッチセットに書いた内容について、提案されたコミットログメッセージや変更自体について質問するかもしれません。これらの質問には返信メッセージで答えるべきですが、レビュー担当者がこれらの質問をしたのは、あなたのパッチセットが理解されるために明確化が必要だったからであることが多いです。

返信で質問に答えるだけで満足し、彼らがあなたの言いたかったことを理解したと言ってくれるのを聞くのはやめましょう。レビュー担当者が困っていた点を明確にするためにパッチを更新し、v2 を準備してください。v1 を説明するために使用した言葉は、レビュー担当者の質問に答えるのに役立つかもしれません。あなたの目標は、v2 を十分に明確にすることであり、次にそれを読む人に同じ説明をする必要がなくなるようにすることです。

コメントに反論する場合は、丁寧な言葉で元のコードの方が良いと思う理由を説明してください。レビュー担当者が依然として同意しない可能性や、コミュニティの残りのメンバーがどちらかの側に意見を述べる可能性があることを覚悟してください。すべてのコードレビューと同様に、当初計画していたものとは異なる方法で行うことについて、オープンマインドでいることが重要です。他のレビュー担当者は、あなたとは異なるプロジェクトの視点を持っており、あなたが思いつかなかった有効な副作用を考えている可能性があります。変更がなぜ提案されたのか、またはレビュー担当者があなたに何を求めているのか不明な場合は、常に明確化を求めることができます。

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

コードに変更を加える場合、最もクリーンな方法、つまり結果として得られるコミットが最も見やすい方法は、git rebase -i (インタラクティブリベース) を使用することです。O'Reilly のこの概要をご覧ください。一般的な考え方は、変更が必要な各コミットを変更することです。こうすることで、間違いのあるパッチ A、問題なく v1 で上流レビューが不要だったパッチ 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 を使用している場合、以前と同じ方法で使用できますが、diff は <topic>..<mybranch> から生成し、作業は master ではなく <topic> をベースにする必要があります。

1. `contrib/` 下のスクリプトはコア `git` バイナリの一部ではなく、直接呼び出す必要があります。Git コードベースをクローンし、`perl contrib/contacts/git-contacts` を実行してください。
scroll-to-top