コミットメッセージは、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.
コミットメッセージを自動的に事前入力する
Git を使用している場合 (場合によっては git-svn を使用してコミットしている場合)、フックによって新しいコミットメッセージを標準形式で自動的に埋め込むことができます。
次のスクリプトを使用して .git/hooks/prepare-commit-msg
ファイルを作成し、chmod +x .git/hooks/prepare-commit-msg
を実行します。
#!/bin/bash
COMMIT_MSG_FILE=$1
COMMIT_SOURCE=$2
if [ $COMMIT_SOURCE ]; then
# A messages is already being provided via `commit -m`, rebase, etc.
exit 0;
fi
template="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.
Props person, another.
Fixes #30000. See #20202, #105.
#
# See https://make.wordpress.org/core/handbook/best-practices/commit-messages/ for more detailed guidelines."
# Wrapping the variable in quotes preserves the newlines, because BASH is weird.
echo "$template" > $COMMIT_MSG_FILE
コミッター向けのその他のヒント
これらはコミットメッセージそのものに関するものではありませんが、以下のガイドラインは覚えておくとよいでしょう。
RC のフェーズでは、コミットされる前にすべてのパッチは2人目のコミッターのレビューを受ける必要があります。
コミットの前
- パッチが受け入れられるかどうか疑問がある場合は、他のコミッターにセカンドオピニオンを求めてください。
- 変更された行がコーディング規約に準拠していることを確認してください。
- PHP
- 変更されたすべてのファイルのすべての行をチェックするには、
phpcs $(git diff trunk --name-only)
またはphpcs $(svn stat | grep "\(M \|A \)" | grep -v "external item" | cut -c8-)
を実行します。 - 変更された行だけをチェックするには、wp-dev-lib をクローンし、
DIFF_BASE=trunk DEV_LIB_ONLY=phpsyntax,phpcs /path/to/wp-dev-lib/pre-commit
を実行します。ローカルブランチがtrunk
以外である必要があり、変更がコミットされているか、コミット用にステージされている必要があることに注意してください。ステージされていない変更はスキャンされません。 - これらのコマンドは、Bash でエイリアスを作成することをおすすめします。
- 変更されたすべてのファイルのすべての行をチェックするには、
- JavaScript
npm run grunt jshint
を実行します。これはnpm run grunt precommit
でも自動的に行われます。
- HTML、CSS、a11y
- これらは手動でチェックする必要があります。
- PHP
npm run grunt build && npm run grunt precommit
を実行します。これにより、PHP と JavaScript の自動テストスイートが実行され、CSS や画像などのさまざまなタスクも実行されます。- 変更内容によっては、PHPUnit をさまざまなフラグをつけて手動で実行する必要があるかもしれません。
- 最後にもう一度完全な diff をチェックします (
svn diff
)。Git を使用している場合は、インタラクティブなステージング (git add -p
) は個々のチャンクをレビューするのに良い方法です。 - 変更されたファイルのリストをチェックし (
svn stat
)、新しいファイルが追加されていることを確認します。ここで新しいファイルの内容の再確認をおすすめします。新しいファイルを追加するパッチを適用すると、新しいファイルの内容が重複する場合があるためです。また、新しいファイルの名前が$_old_files
配列にあるものと同じでないことを確認してください。そうしないと、すぐにまた削除されてしまいます。もし同じ名前がある場合は、同じ名前のファイルがいつ追加され、戻されたかを示すメモを添えて、配列からその行をコメントアウトしてください。その行は削除しないでください。 - ファイルを削除する場合は、それらを
$_old_files
配列に追加します。 svn switch ^/branches/4.3 && svn merge -c 12345 ^/trunk
を使用して、trunk
からリリースブランチへのコミットを「チェリーピック」できます。コミットする前にメッセージを編集するように求められます。詳しくはコミットのバックポートを参照してください。- リリースのタグ付けとブランチの手順は、メジャーバージョンのリリースのコアセクションページにあります。
- ヒント: 追跡されていないファイルを含めずに変更されたファイルを表示するには、次のように Bash のエイリアスまたは関数として追加してください:
svn stat --ignore-externals | grep '^[^?X]'
コミットの後
- 他の環境でテストが失敗した場合に備えて、GitHub Actions で対応するジョブを監視します。