コミットメッセージ

コミットメッセージは、WordPress がどのように開発されてきたかを示す重要な要素です。チェンジセットそのものとともに、プロジェクトの歴史の重要な一部です。私たちは、同世代の人々 (コア開発者達、プラグイン開発者、コア開発に関わる人々)、将来の貢献者、そしてコンピューターという対象者の読者に向けてコミットメッセージを書きます。優れたコミットメッセージは、これらの対象者のそれぞれに有益です。コミットメッセージは、チェンジセットの「内容」と「理由」を記述します。「どのように」は diff 自体によって記述されます。

たとえあなたがコミッターでなくても、WordPress への貢献や自分のプロジェクトでこれらのガイドラインを活用できます。ここで概説されている懸念事項に配慮した方法でパッチを記述することで、あるいは自分自身でコミットメッセージを作成することで、コミッターがあなたの貢献を迅速に処理しやすくなります。

注意: 同じコミットで複数のブランチにコミットしないでください。これは、少なくとも Git ミラーを壊すことになります。

フォーマット

コミットメッセージの完全な形式は次のとおりです:

Component: Brief summary.

Longer description with more details, such as a `new_hook` being introduced with the context of a `$post` and a `$screen`.

More paragraphs can be added as needed.

Example usage:

{{{
// multi-line code snippet
$add_filter(‘some_new_filter’, ‘some_filter_callback’);
}}}

Follow-up to [27195], [41062].

Reviewed by a-fellow-committer, maybe-multiple.
Merges [26851] to the x.x branch.

Props person, another.
Fixes #30000. See #20202, #105.

グローバルガイドライン

各行は大文字で始まり、ピリオドで終わらせます。
Trac と Slack で適切な書式設定が適用されるようにするために、関数名やフック名などのコードはバッククオートの内側に表示します。
概要以外は文字数制限はありません。手動で行を折り返さないでください。
空白行を入れるべき箇所と入れるべきではない箇所に注意してください。
チケット番号の前には番号記号 #20202 が付き、角括弧内のリビジョン番号 [30000] は、Trac、Slack、そして make/core で自動リンクされます。
貢献者の統計を生成するツールが混同しないように、props セクションの外では props という単語の使用を避けてください。プロパティについて話す場合は、完全な単語を使用してください。それ以外の場合は、類義語辞典を参照してください。

簡単な要約

コミットメッセージの最初の行は、チェンジセットの簡単な要約です。これはメールの件名や Trac の変更履歴、および git log --format=oneline などのほとんどの VCS のログ形式で目立つ機能で使用されます。要約は目につきやすいため、スペースの制限内でできるだけ説明的な内容を作成することが重要です。

ガイドライン

1行であり、改行を入れてはいけません。
およそ50文字以内、長くても70文字までにします。ログ閲覧ツールはほぼすべて、コミットメッセージの最初の行がこの制限内に収まることを期待しているので、これは重要です。この厳しい制限は、コミットの本質について批判的に考えさせることになるかもしれません。短い文章で変更を説明できない場合、コミットが必要以上に大きなものであるかもしれません。
接頭辞としてコンポーネント名付きの要約、または変更の要点を付けられます。このような接頭辞をつけることで、貢献者が興味のあるコミットを変更履歴から探しやすくなるかもしれません。例として、[33901]、[33883]、[33848] を参照してください。接頭辞も50/70文字にカウントされることに注意してください。
可能であれば、「Relaxes term ID comparisons…」の代わりに「Relax term ID comparisons…」という命令形を使用します。

説明

コミットに関するより長い説明には、そのコミットの詳細と開発者への影響を含めるべきです。これには、新しいフック、「gotchas (見落としやすい点)」、検討された他の解決策、背景などが含まれるかもしれません。説明に何を書くかを決める際には、読み手を意識してください。読み手はたとえば、コミットメーリングリストをフォローしている開発者、各リリースの開発者ノートや WordPress Core Weekly のために情報をまとめているボランティア、そして、誰が、何を、なぜ、行ったのかを解明しようとしている未来のコード開発者などです。

ガイドライン

要約と空白行で区切ってください。
必要に応じて、空白行で区切って複数の段落にできます。コミットメッセージが最終的なチェンジセット自体よりも冗長になることは不合理ではありません。
要約とは異なり、行を手動で折り返す必要はありません。必要に応じて、ログビューアが説明を自分で折り返すことができます。
段落の代わりにリストを使用することが良い場合がありますが、これはコミッターの裁量によって決まります。
props、backport、backports という単語は避けてください。

Follow-up to (フォローアップ)

特定のチェンジセットのテストの追加や修正の迅速なフォローなど、コミットが以前の作業に直接関連している場合は、それらのチェンジセットへのリンクとともに「フォローアップ」を使用する必要があります。コミットをバックポートする場合は、代わりに「レビューした人とマージ」セクションに従ってください。

ガイドライン

先頭には空白行が必要です。
チェンジセットは角括弧で囲んでください。

Reviewed By and Merges (レビューした人とマージ)

コードをバックポートする場合、マージされるコードとレビューした人を示すために Reviewed By and Merges セクションを使用します。チャットやメールでコミットを確認できるように、マージ先のブランチを指定してください。レビューのために、dev-reviewed キーワードを使用して Trac に記録することをおすすめします。

ガイドライン

この2行セットの前には空白行が必要です。
「Reviewed By」の行と「Merges」の行の間には改行が必要ですが、間に空白行があってはなりません。
複数のコアコミッターがレビュアーとして言及される場合がありますが、その場合はカンマで区切ってください。
コードを移動するタスクはバックポートと呼ばれますが、backport、backports、および backporting という単語はコミットメッセージ内のどこにも使用しないでください。
別のコミッターによって行われたコミットをバックポートする場合、そのコミッターのユーザー名がまだ含まれていない場合は、props のリストに追加します。

Props (称賛)

パッチ、更新されたパッチ、提案されたコード、デザイン、ライティング、ユーザーテスト、その他多大な時間と労力を費やして最終的なコミットに貢献したすべての人に称賛がおくられるべきです。ユーザー名はクレジットリストと WordPress.org プロフィールのために解析されます。

バグレポートの場合、バグの報告者にも props が与えられるべきです。

重複としてクローズされたチケットも、props に値する貢献が含まれている可能性があるためチェックしてください。

ガイドライン

先頭には空白行が必要です。
「Props」と w.org ユーザー名の間にはセミコロン (:) を入れないでください。
ユーザー名は @ (アット) 記号で始めることはできません。
ユーザー名はカンマとスペースで区切ってください。正規表現: /^props (\s*([^,]+),?)+$/
タイプミスを避けるため、ユーザー名はコピー & ペーストしてください。
ユーザーの表示名にスペースがある場合は、w.org プロフィールの URL のスラッグを使用してください。たとえば、Trac の Frank Klein は frank-klein として props を取得する必要があります。
props 行には、props、wordpress.org ユーザー名、スペース、句読点のみを含めてください。
props 行はピリオドで終わらせます。

自分の props

大きな機能、API、特にやっかいなバグなど、コミットが複数の人関わった多大な努力の結果である場合は、自分自身に props を与えてください。
一般的に、貢献者にパッチに対するフィードバックを提供し、反復する機会を与えることが推奨されるプロセスです。ただし、コミッターであるあなたがパッチのアイデアを完成させる場合には、「props X for initial patch.」と書くこともできます。
コミッターがコミットの前にスタイルを調整したり、ロジックを並べ替えたり、あるいは単純なエッジケースを考慮したりするのはよくあることです。このような場合、自分自身を省略してください。コミット上のあなたの名前は、あなたがそれをレビューしてテストしたことを暗示しており、これはコミットの内容と同じくらい重要です。
自分自身のコードをコミットする場合は、props が前提となりますので、ここでも自分自身を省略します。

貢献者へ props を付与することに関する詳細なガイドについては、ハンドブックの貢献者の帰属 (「props」) ページを参照してください。

チケットリファレンス

Trac は、「fixes」や「see」として参照されたチケットにコメントとしてコミットメッセージを追加します。コミットメッセージに「Fixes #12345」というテキストが含まれている場合、Trac はチケット#12345をクローズし、まだ所有者がいなければあなたを所有者にします。

ガイドライン

チケットリファレンスは、props の直下の行に記述してください。props がない場合は、空の改行で上のコンテンツと区切ります。
複数のチケットはカンマとスペースで区切ります。
修正されたチケットと関連されたチケットの両方を参照する場合は、「Fixes」で始めて各セットをピリオドで終了します。たとえば「Fixes #19867, #9864. See #31696.」などです。セット内の項目が多い場合は、別の行に入れます。
チケット番号を入れ忘れた場合は、チケットにコメントを残します (例:「Fixed in [changeset_number]」。オプションでコミットメッセージのコピーを付けると、トレーサビリティを確保しやすくなります)。

例

悪い:

Don't use strict comparisons for term IDs. props booneiscool. fixes #3398.

まあまあ良い:

Fixing `wp_dropdown_categories()` and other places that use term IDs.

props boonerocks. fixes #20000.

良い:

Taxonomy: Relax term ID comparisons.

Term IDs are sometimes provided as strings. This is particularly evident in `wp_dropdown_categories()`, where the `selected` argument was not being respected. Plugin authors should also be wary of using strict comparisons for term IDs.

Props booneistheman.
Fixes #13237.