コミットメッセージ

コミットメッセージは、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.

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

一般的に、コミットメッセージの各行は大文字で始まり、ピリオドで終わります。関数名やフックのようなコードは、Trac や Slack で適切な書式になるように、バッククオートの内側に記述する必要があります。チケット番号の前に数字記号 #20202がつき、角括弧内のリビジョン番号 [30000] は、Trac、Slack、そしてここ make/core で自動リンクされます。

コミットメッセージの最初の行は、チェンジセットの簡単な要約です。これはメールの件名や 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 のために情報をまとめているボランティア、そして、誰が、何を、なぜ、行ったのかを解明しようとしている未来のコード開発者などです。

• 要約と説明の間は空白行で区切ってください。
• 必要であれば、空白行で区切って複数の段落にできます。コミットメッセージが最終的な変更セットそのものよりも冗長である場合もあります。
• 要約とは異なり、行を手動で折り返す必要はありません。必要に応じて、ログビューアが自動で説明を折り返します。

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

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

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

• 先頭には空白行が必要です。
• ユーザー名は @ (アット) 記号で始めることはできません。
• ユーザー名はカンマとスペースで区切ってください。正規表現: /^props (\s*([^,]+),?)+$/
• タイプミスを避けるため、ユーザー名はコピー & ペーストしてください。
• ユーザーの表示名にスペースがある場合は、w.org プロフィールの URL のスラッグを使用してください。たとえば、Trac の Frank Klein は frank-klein として props を取得する必要があります。
• Props は自由に与える側に回ってください。Props は貢献者に大きな励ましを与えます。
• もし誰かに props を与えることを忘れた場合、その人が現在のリリースですでに props を与えられているかどうか確認してください。与えられていれば、いずれにしてもリリースクレジットに含まれるため、長期的には問題とはなりません。まだ props が与えられていなければ、リリースコーディネーターに連絡し、リリース日にその人が追加されるようにできます。また、礼儀として Slack やチケットのコメントで貢献者に連絡を取り、コミットメッセージに名前がなかったことをお詫びし、彼らの貢献が評価されることとその方法を伝えることを推奨します。

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

• A Note About Git Commit Messages
• 5 Useful Tips For A Better Commit Message
• How to Write a Git Commit Message

原文 / 日本語訳

最終更新日: 2023年10月8日