このドキュメントで後述するさまざまなガイドラインの背景にある理由を理解するために、まず、このプロジェクトにおける典型的なパッチシリーズのライフサイクルがどのように進むかを理解しましょう。

以下のセクションでは、このようなライフサイクルでパッチが効果的にレビューされるのを助けるための多くの技術と慣習がリストされています。

予備的なステップとして、まず作業の開始点を選択する必要があります。通常、これはブランチを選択することを意味しますが、技術的には特定のコミット（通常はブランチの HEAD、または先端）です。

注意すべき重要なブランチがいくつかあります。具体的には、gitworkflows[7] で議論されているように、4つの統合ブランチがあります。

リストの下にあるブランチは、通常、それより上位のブランチの子孫です。たとえば、maint は master よりも「古い」ブランチです。なぜなら、master は通常 maint の上にパッチ（コミット）を持っているからです。

また、他の貢献者からの作業を含む「トピック」ブランチもあります。トピックブランチは、Gitメンテナー（のフォーク）によって、メーリングリスト上の現在の受信中の貢献を整理するために作成され、定期的な「What’s cooking in git.git」アナウンスで項目化されます。トピックブランチの先端を見つけるには、git log --first-parent master..seen を実行し、マージコミットを探します。このコミットの2番目の親がトピックブランチの先端です。

適切な開始点を選択するための1つの指針があります。一般に、常に変更に関連する最も古い統合ブランチに基づいて作業してください（gitworkflows[7] の「Merge upwards」を参照）。この原則は、ほとんどの場合、新しい作業の開始点は、以下のケースに基づいて maint または master の最新の HEAD コミットであるべきだということを意味します。

これは、master への昇格の現実的な機会を望むのであれば、next や seen はあなたの作業の不適切な開始点であることを意味します。これらは新しい作業のベースとして使用されるように設計されていません。これらは単に進行中のトピックがうまく機能することを保証するためにのみ存在します。これが、next と seen の両方がメーリングリスト上の受信パッチと頻繁に再統合され、以前のバージョンを置き換えるために強制プッシュされる理由です。next の上に文字通り構築されたトピックは、next 内の他のすべてのトピックを引きずり込まなければ master にマージすることはできません。その中にはまだ準備ができていないものもあるかもしれません。

例えば、あなたがツリー全体にわたる変更を行っている間に、他の誰かが自身のツリー全体にわたる変更を行っている場合、あなたの作業は他の人の作業と大きく重複する可能性があります。この状況では、next を開始点として使用したい誘惑に駆られるかもしれません（なぜなら、他の人の作業が含まれているからです）。しかし、そうすると、他の人の作業だけでなく、すでに next に統合されている他の貢献者からのあらゆるランダムなものすべてに依存することになります。そして、next が新しいバージョンで更新されるとすぐに、メンテナーがクリーンに適用できるように、あなたの作業すべてはとにかくリベースする必要が生じます。

例外中の例外で、あなたが絶対に next には存在するが master には存在しない、選ばれたいくつかのトピックブランチに依存しなければならない場合、master をフォークし、必要なトピックブランチをそれにマージすることで、独自のカスタムベースブランチを作成したいと思うかもしれません。その後、このベースブランチの上に作業することができます。しかし、このベースブランチはあなただけが知っているプライベートなものであることに留意してください。そのため、パッチをリストに送る準備ができたら、カバーレターでその作成方法を必ず伝えてください。この重要な情報があれば、他の人はあなたのベースブランチを自分の環境で再作成して、あなたの作業を試すことができます。

最後に、システムの一部には、独自のソースコードリポジトリを持つ専門のメンテナーがいることに注意してください（以下の「サブシステム」セクションを参照）。

あなたのパッチが本当に些細なものでない限り、作業ツリーとコミットヘッドの間で生成されたパッチを送信すべきではありません。代わりに、常に完全なコミットメッセージでコミットを作成し、リポジトリから一連のパッチを生成してください。これは良い習慣です。

変更（複数可）について、人々が実際にパッチテキストを読んでコードが説明をどれだけうまく実行しているかを判断しなくても、それが良いことであるかどうかを判断できる程度に詳細な説明を付けてください。

説明が長くなりすぎたら、おそらくコミットをより細かな部分に分割する必要があるというサインです。とは言え、レビュアーがパッチをチェックするのに役立つこと、そして将来のメンテナーがコードを理解するのに役立つことを簡潔に記述したパッチは、最も美しいパッチです。件名で要点をうまく要約し、変更の動機、変更のアプローチ、そしてもし関連があれば以前のバージョンとどのように実質的に異なるかを記述した説明は、すべて良いものです。

修正するバグのテストがあることを確認してください。t/README を参照してください。

新しい機能を追加する際は、その機能が本来のタイミングで新しい動作をトリガーすること、そして本来ではないタイミングでトリガーしないことを示す新しいテストがあることを確認してください。コード変更後は、テストスイート全体がパスすることを確認してください。バグを修正する際は、誰かが誤って修正を壊した場合に回帰を防ぐための新しいテストがあることを確認してください。また、作業を next と seen にマージしてみて、テストがまだパスすることを確認してください。進行中の他の人々のトピックは、あなたのトピックでやろうとしていることと予期せぬ相互作用をする可能性があります。

https://github.com/git/git のフォークにプッシュすると、そのCI統合を使用してLinux、Mac、Windowsで変更をテストします。詳細はGitHub CIセクションを参照してください。

更新された動作を説明するためにドキュメントを更新し、結果として得られるドキュメントセットが適切にフォーマットされることを確認することを忘れないでください（Documentation/doc-diff スクリプトを試してください）。

現在、綴りや文法について米語と英国英語の規範が自由に混ざっており、これは多少残念なことです。矛盾を修正するためだけに多くのファイルを修正する大規模なパッチは歓迎されません。そのようなパッチから生じる他の変更との潜在的な衝突は、それだけの価値がありません。私たちは、米語を支持して矛盾を段階的に解消することを好みます。これは、近くの他の実際の作業を行う際の副次的な効果として、小さく消化しやすいパッチで行われます（例：明確にするために段落を書き換えながら、英国英語の綴りを米語に変える）。明らかな誤植の修正（「teh」→「the」）は、他のドキュメント変更とは別の独立したパッチとして提出されることが望ましいですが、より歓迎されます。

ああ、もう一つ。空白については厳しくチェックします。あなたの変更が templates/hooks--pre-commit に同梱されているサンプルプリコミットフックのエラーをトリガーしないことを確認してください。これを確実にするために、コミットする前に変更に対して git diff --check を実行してください。

変更内容を説明するログメッセージは、変更内容そのものと同じくらい重要です。コードは、周囲のコードとの連携方法を十分に説明するためにコード内コメントで明確に記述されているかもしれませんが、将来コードを修正したり強化したりする必要がある人々は、いくつかの理由からあなたのコードがなぜそのように動作するのかを知る必要があります。

あなたのログメッセージの目標は、将来の開発者を助けるために、変更の背後にある*理由*を伝えることです。レビュアーはまた、あなたの提案するログメッセージがこの目的に十分に役立つことを確認します。

コミットメッセージの最初の行は短い説明であるべきです（50文字がソフトリミットです。git-commit[1] の DISCUSSION を参照してください）。そして、終止符はスキップすべきです。また、ほとんどの場合、最初の行に「area: 」というプレフィックスを付けるのが慣例です。ここで area は、変更されるコードの一般的な領域のファイル名または識別子です。例えば、

どの識別子を使用すべきか迷った場合は、修正しているファイルで git log --no-merges を実行して、現在の慣例を確認してください。

「area:」プレフィックスの後のタイトル文は、末尾のピリオドを省略し、その最初の単語は、文頭の単語だからという理由以外に大文字にする理由がない限り、大文字にしません。(大文字の省略は、タイトルの「area:」プレフィックスの後の単語にのみ適用されます。) 例: 「doc: clarify...」であって「doc: Clarify...」ではない、または「githooks.txt: improve...」であって「githooks.txt: Improve...」ではない。ただし、「refs: HEAD is also treated as a ref」は正しく、HEAD は文の途中に出てきても大文字で表記します。

本文には、次のような意味のあるコミットメッセージを提供する必要があります。

現状を説明する問題文は現在形で書かれます。「コードは入力Yを与えられたときにXを行う」と書き、以前のコードが入力Xを与えられたときにYを行っていた」とは書かないでください。「現在」と言う必要はありません。プロジェクトの慣習により、問題文の現状はあなたの変更**なし**のコードに関するものです。

変更内容を命令形で記述してください。例えば、「[このパッチは] xyzzy に frotz を実行させる」や「[私は] xyzzy を frotz を実行するように変更した」ではなく、「xyzzy に frotz を実行させよ」のように、コードベースにその動作を変更するよう命令しているかのように記述します。説明が外部リソースなしで理解できることを確認してください。メーリングリストのアーカイブへのURLを与えるのではなく、議論の関連するポイントを要約してください。

履歴の「より安定した」部分（つまり、maint、master、next などのブランチ）にある別のコミットを参照したい理由はいくつかあります。

より安定したブランチ（master、maint、next など）上のコミットを参照する場合、次のように「省略されたハッシュ (件名、日付)」の形式を使用します。

gitk の「コミット参照をコピー」コマンドを使うと、この形式（件名が二重引用符で囲まれたもの）を取得できます。または、この git show の呼び出しも使えます。

または、--pretty=reference に対応していない古いバージョンのGitでは、

誰が何をしたかをより良く追跡するために、私たちは、パッチを作成したこと、または私たちと同じライセンスでパッチを転送する権利があることを、「サインオフ」することで認証するよう求めています。サインオフなしでは、あなたのパッチを受け入れることはできません。

あなたが以下の D-C-O を証明する場合（かつその場合に限り）、

次のような「Signed-off-by」トレーラーをコミットに追加します。

この行は、Git のコミットコマンドを -s オプションで実行すると追加できます。

他の人のパッチを上記のD-C-Oのルールに従って転送する場合でも、あなた自身の Signed-off-by トレーラーを配置できることに注意してください。実際、そうすることを推奨します。変更の真の作者に適切に帰属させるために、本文の先頭に「From: 」行を配置することを忘れないでください（上記の（2）を参照）。

この手順はもともとLinuxカーネルプロジェクトから来たものなので、私たちのルールは彼らのものとかなり似ていますが、パッチをサインオフすることが具体的に何を意味するかはプロジェクトによって異なるため、あなたが慣れているプロジェクトとは異なるかもしれません。

また、Signed-off-by トレーラーには実名が使用されることに注意してください。実名を隠さないでください。

よろしければ、最後に以下の追加トレーラーを付けることができます。

状況に応じて独自のトレーラーを作成することもできますが、上記で強調したこのプロジェクトの一般的なトレーラーのいずれかを使用することをお勧めします。

トレーラーの最初の文字のみを大文字にしてください。つまり、「Signed-Off-By」ではなく「Signed-off-by」、「Acked-By」ではなく「Acked-by:」を好んでください。

Gitベースのdiffツールはunidiffを生成しますが、これが推奨される形式です。

パッチがファイル名の変更を伴う場合でも、git diff や git format-patch の -M オプションを恐れる必要はありません。受信側で問題なく処理できます。

パッチにコメントアウトされたデバッグコードを追加したり、パッチが達成しようとしていることと関係のない余分なファイルを含めたりしないようにしてください。生成したパッチをレビューして、正確性を確認してください。送信する前に、「開始点を選択してください」セクションで選択した開始点にきれいに適用されることを確認してください。

パッチへの変更を改訂する際、他の進行中のトピックとの競合の可能性を認識することが重要です。これらの潜在的な競合を効果的に乗り越えるには、以下に示す推奨手順に従ってください。

（ヨハネス・シクスト）

（リーナス・トーバルズ）

（ダニエル・バーカロウ）

git-format-patch[1] の MUA-SPECIFIC HINTS セクションを参照してください。

*Summary* バッファの「|」を使って現在のメッセージを外部プログラムにパイプすることができます。これは git am を実行するのに便利な方法です。ただし、メッセージがMIMEエンコードされている場合、プログラムにパイプされるのは、MIMEを解凍した後に *Article* バッファで表示される表現です。これは2つの理由から、あなたが望むものではないことが多いです。非ASCII文字（特に人名）や空白（パッチでは致命的）が崩れる傾向があります。この問題を回避するには、「C-u g」を実行して生の形式でメッセージを表示してから「|」を使ってパイプを実行することができます。