Submitting Patches

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

以降のセクションでは、 上記のようなパッチのライフ・サイクルの中で、 効果的にレビューしてもらえるためのさまざまなテクニックや慣習を紹介します。

事前の準備として、 まず作業の起点となる場所を選ぶ必要があります。 これは通常はブランチを選ぶことを意味しますが、 厳密に言えばそれは実際には特定のコミットを選ぶことです(たいていはそのブランチの HEAD、 つまり先端を選びます)。

注意すべき重要なブランチいくつかあります。 gitworkflows(7) で説明されているとおり、 以下の 4 つの統合ブランチがあります:

このリストの下の方にあるブランチは通常、 その上にあるブランチの子孫です。 たとえば、 maint は、 master よりも「古い」ブランチです。 これは、 master には通常、maint の更にその上にパッチ(コミット)があるためです。

また、 トピック・ブランチ(topic branches)と呼ばれるものもあります。 これらは他の貢献者達からの作業を含むブランチです。 トピック・ブランチは、 Gitのメンテナーが(メンテナー自身のフォーク内に)、 メールリストに届いている現在の貢献パッチを整理・管理するために作成し、 定期的に配信される "What’s cooking in git.git" 案内メールの中で個別に紹介されます。 あるトピック・ブランチの先端(tip)を調べるには、 git log --first-parent master..seen というコマンドを実行してマージ・コミットを探してください。 このマージ・コミットの 2番目の親(second parent)が、 そのトピック・ブランチの最新コミット(tip)になります。

適切な起点を選択するための原則はひとつだけです: それは、 「あなたの変更が関係する一番古い統合ブランチを常にベースにせよ」ということです(詳細は gitworkflows(7) の「Merge upwards」のセクションを参)。 この原則の意味は、ほとんどの場合、新しい作業の起点は以下のルールに従って maint または master の最新コミット(HEAD)にすべきだということです:

これが意味するのは、 あなたの作業を現実的に master に取り込んでもらいたいのであれば、 next や seen を起点にするのは不適切だということです。 それらは新しい作業のベースとして設計されているわけではなく、 ただ現在進行中のトピック同士がうまく共存できるかを確認するためだけに存在しています。 そのため、 next と seen はメーリングリストに届く新しいパッチを頻繁に取り込んで再統合され、 以前の自分自身を上書きする形で強制プッシュされます。 文字通り next の上に構築されたトピックは、 next に入っている他のまだ準備ができていないトピックすべてを引きずり込むことになるため、 master にマージすることはできません。

たとえば、 あなたがツリー全体にわたる変更を行っているときに、 別の人もまた別のツリー全体にわたる変更を行っているとします。 この場合、 あなたの作業と他人の作業が大きく重複する可能性があり、 next を起点にしたくなる誘惑に駆られるかもしれません(なぜなら next にはすでに他人の作業が取り込まれているからです)。 しかしそうしてしまうと、 あなたは他人の作業だけでなく、 next にすでに統合されている他の貢献者達によるさまざまなものすべてに依存することになります。 そして next が新しいバージョンで更新された瞬間に、 あなたの作業すべてを再ベースしないとメンテナーがきれいに適用できなくなります。

本当にごく例外的な状況で、 next には入っているが master にはまだ入っていないごく少数のトピック・ブランチにどうしても依存しなければならない場合は、 master をフォークして必要なトピック・ブランチだけをそこにマージすることで、 自分専用のベース・ブランチを作成してもかまいません。 そしてその上で作業を進めます。 ただし、 このベース・ブランチはあなただけが知っているプライベートなものになります。 したがって、 パッチをメーリングリストに送るときは、 カバー・レターで「どのようにしてこのベース・ブランチを作ったか」を必ず明記してください。 この情報がないと、 他の人があなたの作業を試すために同じベースを再現できなくなります。

最後になりますが、 システムの一部には専任のメンテナーがいて、 別リポジトリーでソース・コードを管理しているサブ・システムもあります(下記「Subsystems」セクション参照)。

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

変更内容は、 実際にパッチのコードを読まなくても「この変更は正しいか」「やるべきことか」を判断できるくらい十分に詳しい説明を書いてください。 説明を読んだだけで「このコードが約束していることを本当にちゃんと実現しているか」を評価できるレベルにしてください。

あなたの説明が長くなりすぎるようでしたら、 それはおそらくコミットをさらに細かく分割すべきサインです。 とはいえ、 レビュアーがパッチをチェックしやすくなり、 将来のメンテナーがコードを理解しやすくなるような、 わかりやすい説明が一番美しいパッチです。 メールの件名欄で要点をうまくまとめ、 そして、 変更の動機や、 この変更が取ったアプローチや、 必要に応じて以前のバージョンとどう大きく違うかを記述している説明は、 どれも素晴らしいものです。

あなたが修正しようとしているバグに対して、 必ずテストを用意してください。 やり方については t/README を参照してください。

新しい機能を追加するときは、 その機能が、 あるべきときに新しい振る舞いを引き起こすこと、 そしてあるべきで無いときには引き起こさ無いこと、 を確認できる新しいテストを必ず用意してください。 コードを変更した後は、 全体のテスト・スイートが通ることを確認してください。 バグを修正するときは、 誰かが誤ってあなたの修正を壊した場合に失敗するような新しいテストを追加し、 再発(regression)を防いでください。 また、 自分の作業を next および seen にマージしてみて、 テストがまだ通ることを確認してください。 他の人が進行中のトピックが、 あなたのトピックと予期しない相互作用を起こす可能性があります。

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

更新された振る舞いを説明するために、 ドキュメントも必ず更新してください。 そして、 ドキュメント全体が正しくフォーマットされることを確認してください(Documentation/doc-diff スクリプトを試してください)。

現在、 スペルや文法については米国英語(US)と英国英語(UK)がかなり混在しており、 これは残念な状況です。 ただし、 こうした不統一のためだけに、 ありとあらゆるファイルを触るような巨大なパッチは歓迎されません。 そういうパッチは他の変更との衝突を引き起こしやすく、 コストに見合いません。 我々は、米国英語(US)を優先しつつ、 不統一を徐々に解消していく方針です。 その際は「他の実質的な作業(たとえば文章をわかりやすく書き直すなど)」のついでに、 近くの箇所を小規模で飲み込みやすいパッチとして修正していくのが望ましい形です(たとえば、 段落を明確化しながら en_UK 表記を en_US に直すなど)。 一方で、 明らかなタイポ修正("teh" → "the" など)は大歓迎です。 タイポ修正はドキュメントの他の変更とは別に、 独立したパッチとして提出していただけると助かります。

ああそれと、 もう一つ大事なこととして、 我々は空白文字(whitespaces)に対して非常に厳しいです。 あなたの変更が、 templates/hooks--pre-commit に同梱されているサンプルの pre-commit フックでエラーにならないようにしてください。 それを防ぐために、 コミットする前に必ず git diff --check を実行して、 あなたの変更に問題がないか確認してください。

変更内容を説明するログ・メッセージは、 変更そのものと同じくらい重要です。 あなたのコードがとてもきれいに書かれていて、 インライン・コメントで周囲のコードとの関係が十分に説明できていたとしても、 将来あなたのコードを修正したり強化したりする人は、 「なぜ」そのコードがそのような動作をするのか、 を知る必要があります。 その理由は以下の通りです:

ログメッセージの目的は、あなたの変更の「なぜか」(why)を伝え、将来の開発者を助けることです。 レビュアーも、 あなたが提案したログ・メッセージがこの目的をしっかり果たせているかを確認します。

コミット・メッセージの1行目は短い要約で、 50文字分が目安(詳細は git-commit(1) の DISCUSSION 参照)。 文末にピリオドは付けません。 また、 ほとんどの場合、1行目の先頭に "area: " という形でプレフィックスを付けるのが慣例です。 ここで area とは、 変更しているコードの一般的な領域を示すファイル名や識別子のことです。 例えば以下のようなのです

どの識別子(identifier)を使えばいいか迷ったら、 変更しているファイルに対して 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 をさせる」（make xyzzy do frotz）のように書きます。 「[このパッチは] xyzzy に frotz をさせる」や「[私が] xyzzy を frotz をするように変更した」のような書き方は避けてください。 コードベースに対して「振る舞いを変えなさい」と命令しているような形にします。 また、説明は外部の資料を見なくても理解できるようにしてください。 メーリングリストのアーカイブへの URL を貼るのではなく、 議論で重要だったポイントを自分で要約して書いてください。

履歴の「より安定した」(more stable)部分（つまり maint や master や next などのブランチ）に存在する別のコミットを参照したくなる理由がいくつかあります:

(master や maint や next のような)より安定したブランチ(more stable branch)にあるコミットを参照するときは、 "abbreviated hash (subject, date)" 形式("省略ハッシュ (件名, 日付)")を使って下さい。 例えば以下のようなのです:

gitk の "Copy commit reference" コマンドを使うと、 この形式(件名がダブル・クオートで囲まれた形)で取得できます。 あるいは、 以下の git show の呼び出しでも同じ形式が得られます:

or, on an older version of Git without support for --pretty=reference:< または、 --pretty=reference をサポートしていない古いバージョンの Git では以下のようにします:

誰が何をしたかの追跡状況を改善するため、 あなたのパッチを「サイン・オフ」(signing off)することで、 あなたがそのパッチを自分で書いたか、 または我々と同じライセンスでそれを渡す権利があることを証明していただくようお願いしています。 サインオフ(sign-off)が無い場合、 私たちはあなたのパッチを受け入れることができません。

以下の D-C-O を認証する場合(そして、 その場合に限る):

以下のような "Signed-off-by" トレーラーをあなたのコミットに追加します:

-s オプションを指定して git-commit コマンドを実行することにより、 Git がこの行を追加するようにすることもできます。

注意: 上記の D-C-O のルールに従って他人のパッチを転送するときは、 あなた自身の Signed-off-by トレーラーを付けることができることに注意してください。 実際、 そうすることを強く推奨します。 変更の本当の作者に適切にクレジットを帰属させるために、 本文の先頭にインラインの "From: " 行を置くことを忘れないでください(上記 (2) 参照)。

この手順は元々 Linux カーネル・プロジェクト由来であるため、 我々のルールはそれと非常に似ていますが、 パッチにサインオフ(sign-off)することの正確な意味はプロジェクトごとに異なります。 したがって、 あなたが慣れているプロジェクトのものとは異なる場合があります。

Signed-off-by トレーラーでは匿名投稿は受け付けられないため、 既知の身元を使用してください。 実名を使用するのが一般的ですが、 必須ではありません。 一部の貢献者は実名を使用することに抵抗があるか、 偽名や希望する名前で投稿することを好む場合があることを我々は理解しており、 あなたが使用する名前とメールアドレスが明確で、 かつ識別可能で、 かつ誤解を招く恐れが無い限り、 どちらの場合でもパッチを受け付けます。

このポリシーの目的は、 あなたの貢献について質問が生じた場合に、 あなたに連絡するための十分な情報を持つことです。

あなたの必要に応じて、 末尾に追加のトレーラーを追加できます:

状況によってはあなた独自のトレーラーを作成することもできますが、 我々は、 その代わりに、 上記で明示した、 このプロジェクトで一般的に使用されているトレーラーのいずれかを使用することを推奨します。

トレーラーの最初の文字だけを大文字(capitalize)にしてください。 つまり、 "Signed-Off-By" や "Acked-By" ではなく、"Signed-off-by" や "Acked-by:" が好ましいです。

Developer’s Certificate of Origin(開発者起源証明書)は、 貢献者がプロジェクトへの自分の貢献の出所を知っており、 プロジェクトのライセンスの下でそれを提出する権利があることを証明することを求めています。 AI ツールによって生成された大量のコンテンツを提出する場合、 これを法的に満たすことができるかどうかはまだ明確ではありません。

AI 生成コンテンツに関するもう一つの問題は、 AI に誤りを指摘してもなお、 しばしば幻覚(hallucination;ハルシネーション)を起こしたり、 質の悪いコード・コミット・メッセージの、 ドキュメントや出力(output)を生成してしまう点です。

これらの問題を避けるため、 我々は、 AI 生成らしく見えるものや、過度に形式的で冗長なものや、典型的な AI の粗悪な出力(AI slop)のように見えるものや、 表面上は良く見えるが意味をなさないものや、 送信者が理解しておらず説明できないもの、 は拒否します。

我々は AI ツールを慎重かつ責任を持って使用することを強く推奨します。

貢献者は、 AI に完全な解決策を求め、 それをまるっとコピペするよりも、 AI を使用してステップ・バイ・ステップで自分で解決策を作成するよう導き、 助けてもらうことで、 より多くの利益を得ることが多いでしょう。 また、 送信前に AI をデバッグ(debugging)の助けに使用したり、 明らかなミスや、 改善できる点や、 我々のスタイル・ガイドライン・フィードバック、 に合わない点をチェックしたりすることもできます。

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

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

あなたのパッチにコメント・アウトされたデバッグ・コードが残っていたり、 目的と関係ない余分なファイルが含まれていないようにしてください。 パッチ生成後には必ず内容を確認し、 正確であることを確かめてください。 送信前に、「Choose a starting point」セクションで選んだ起点に対してパッチがきれいに適用できることも確認してください。

あなたがパッチを修正する際は、 他の進行中のトピックと競合する可能性を認識することが重要です。 以下の推奨手順に従うことで、 競合を効果的に回避・解決できます:

(Johannes Schindelin)

(Linus Torvalds)

(Daniel Barkalow)

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

*Summary* バッファで "|" を使用すると、 現在のメッセージを外部プログラムにパイプできます。 これが git am を実行する便利な方法です。 しかし、 メッセージが MIME エンコードされている場合、 パイプされる内容は *Article* バッファで MIME を展開した後に見えている表示形式になります。 これは多くの場合、望ましくない結果になります。 理由は2つあります。 非 ASCII 文字(特に人名)を壊しやすいことと、 空白(whitespaces)を壊すことです(パッチの場合、致命的)。 これを回避するには、"|" でパイプを実行する前に C-u g を押してメッセージを生の形式で表示しておくと上手くいきます。