Gerrit/コミットメッセージの指針

This page is a translated version of the page Gerrit/Commit message guidelines and the translation is 91% complete.

Outdated translations are marked like this.

For repositories that have have a .gitmessage file in the repo (e.g. mediawiki/core), you can encourage yourself to a good commit hygiene, by running the following command in your checked out repo

 git config commit.template .gitmessage

If you like it, you are encouraged to add it to more repos

変更のコミットメッセージは重要な役割を果たします。あなたの変更の中でも、他の人が最初に目にする場所です。

component: Short subject line

More details. The blank line between the subject and body is
mandatory. The subject line is used to represent the commit in
code-review requests, search results, git rebase, logs, and more.

Bug: T54321

構造

件名

コミットメッセージの最初の行は件名 (subject) と呼ばれます。件名は 80 文字未満にする必要があります (50〜70 文字を目指します)。

件名の行では変更を要約します。これはリポジトリに永遠に残ることを心に留めておいてください。
必要に応じて、関連するコンポーネントを件名の前に付けます。コンポーネントは、コミットが変更する全般的な領域のことです。
件名の行では命令形を使用してください。 Avoid stating a fact, like "Badge hides zero" or "Zero in badges", which is ambigious and does not describe a change (good or bad? before or after?). Consider instead "Hide zeroes in badges", "Show zeroes in badges", or "Badge: Restore display of zero".
命令形は、誰かに指示を与えているように聞こえます。"Change", "Fix", "Add", "Remove", "Document", "Refactor" のような単語で始まることがあります。
件名の行は短くし、あなたのコミットが何を変更するかを明確に記述する必要があります。
異なることを行う2つのコミットに対して、同じ件名は使用できないはずです。変更フィード、コードレビューのメール、git-blame のログ、リリースノート、展開 (deployment) の変更履歴などで、あなたの件名が流れてくると、人々は文脈を無視して読んでしまいます。いい件名は、数多くのコミットの中から、特定の興味や関心に関連するかどうかを素早く判断するのに役立ちます。
件名の末尾にピリオド/ドット (.) を付けないでください。

いい例は以下の通り:	悪い例は以下の通り:
"Add Badge::query to query the API" "Avoid API query in SimpleBadge" "Support zeroes in SimpleBadge::add" "badger: Add accessibility labels to form fields" "rdbms: Avoid infinite loop on null input" "htmlform: Change colours to match April 2020 design"	"Added Badge::query method", "Badge can query the API" "Badge doesn't do API queries" "Fixed Badge::query method", "Zeroes work when adding badges" "Implement accessibility fixes" "Fix crash" "Use a better design"

本文

本文を書く際は、以下の質問について考えてください:

この変更を行う必要がある理由は? 現在のコードの何が問題点になっていますか?
この方法で変更する必要がある理由は? 他の方法はありますか?
他のアプローチを検討しましたか? その場合は、それらのアプローチがそれほどよくなかった理由を説明してください。
レビュアーはどのようにして、コードが正しく機能していることをテストまたは検証できますか?

推奨:

… 本文と件名を 1 行の空白行で区切ります。
… 行が最大100文字になるようにメッセージを折り返します。多くのエディターやツールが自動的にこれを行うことができます。72 文字が改行する一般的な文字数です。^[1] ただし、URL は「フィット」させるために分割するとクリックできなくなるため、長くなってもそのままにしてください。
他のコミットを参照するには、I83f83377f2 のような (短い) Gerrit Change-Id、または 51e3fb9a71 のような Git コミットハッシュを使用します。関連する変更がまだマージされていない場合は、常に Gerrit Change-Id を使用します。マージされる際に Git のコミットハッシュが変更され、行き止まりになってしまうためです。

非推奨:

他のコミットを URL や変更番号 (change 番号) で参照しないでください。
- 代わりに、I83f83377f2 のような Gerrit の Change-Id、または 51e3fb9a71 のような Git コミットハッシュを使用します。この種のハッシュは、Gerrit や Gitiles などのリポジトリブラウザーで変更を参照する際に、自動的にリンクに変換されます。また、git show やテキストエディター内など、開発中の Git リポジトリでのナビゲーションも容易に行えるようになります。
- 一方、URL はウェブブラウザーでしか解決できず、固定された場所に遷移するため、コードレビューのワークフローを壊してしまい、ローカルコンテキストから離れることになります。例えば、Git ブラウザーの中では、ハッシュを使用すれば、あるコミットから関連するコミットへ、Gerrit に遷移することなく、同じツール内で素早く移動できます。また、このハッシュは Gerrit で検索することで、それを参照しているコミットを自動的に見つけられます。
- また、変更番号が曖昧になったり、意図したものとは異なるコミットに自動的にリンクされることも問題です。これは、コミットハッシュが数字のみであることがあります。例えば、コミット 665661 は変更 665661 とは別物です。
変更の説明として URL のみを使用するのはやめてください。
- 変更が他の場所での議論や外部の説明文書で正当化される場合は、コミットメッセージ内でキーポイントを要約し、URL も参照するようにしてみてください。

フッターとメタデータ

フッターの最も重要な情報は、Change-Id (必須) と Bug です。

"Bug" と "Change-Id" のメタデータを以下の例とまったく同じように整形し、本文の最終行の後に空行を入れた後に一緒に配置します。

各メタデータフィールドの詳細情報は、下記を参照してください。

例

いい例

jquery.badge: Add ability to display the number zero

Cupcake ipsum dolor sit. Amet tart cheesecake tiramisu chocolate cake
topping. Icing ice cream sweet roll. Biscuit dragée toffee wypas. 

Does not yet address T44834 or T176. Follow-up to Id5e7cbb1.

Bug: T42
Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907

悪い例

Improved the code by fixing a bug.

Changed the files a.php and b.php

Bug: T42
Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907

追加的な例

If the repository you are contributing to has a .gitmessage file (example), use the following command to get a template to guide you in writing a commit message: git config commit.template=.gitmessage

件名

私たちが使用するほとんどのプログラムは、Git コミットを表示する際に件名をプレーンテキストとしてレンダリングします。つまり、URL が機能せず、テキストの選択/コピーができないことがよくあります。したがって、件名の行内で Phabricator タスク、Git コミット、URL には言及しないでください。代わりに、本文またはフッターのメタデータで言及してください。こうすることで、普遍的に選択、コピー、クリックできます。

Gerrit は件名を、メール通知、IRC 通知、検索結果で使用します。
GitHub は件名を以下で使用します: コミット履歴, コミットの件名。
Git CLIは、次のサブジェクトを使用します: git shortlog, git log --oneline, git rebase -i, git show, etc.
MediaWiki のウィキメディア展開ブランチのリリースノート
などなど、盛りだくさんです！

コンポーネント

件名の先頭をコンポーネントにすることで、コミットによってプロジェクトのどの領域が変更されるかを示すこともできます。

以下のいずれかである必要があります:

"installer"、"jobqueue"、"objectcache"、"resourceloader"、"rdbms"など、includes/あるいはincludes/libs以下のPHP クラスのディレクトリです。
PHP クラス名 (Title、User、OutputPage など)。通常、includes/ に下位ディレクトリがないクラスの場合。
* ResourceLoader モジュール名 (「mediawiki.Title」「mediawiki.util」など)。
変更の種類に関連する複数の領域に影響を与える汎用的なキーワード:
- "build" - 開発ワークフローに関連するファイルの変更 (package.json .travis.yml などの更新など) の場合
- "tests" or "test" (depending on directory name) - QUnit や PHPUnit のテストスイート、またはテストスイートランナーのみに影響する変更の場合。

Phabricator

Phabricator のバグまたはタスクを参照するには、コミットメッセージで Txxx 表記を使用してインラインで言及します (例:「That was caused by T169.」)

コミットが (部分的にでも) 解決するか、特にバグに関連することを表現するには、コミットメッセージの末尾にあるフッターに Bug: Txxx を追加します。^[2] (コミットメッセージを修正 (amend) する場合は、Change-Id: 行のすぐ上に挿入します。Change-Id: 行との間に空白行は挿入しません。全体の構造ルールに従って、本文と件名を 1 行の空白行で区切ることを忘れないようにしましょう。)

Bug: T169

ボットは Phabricator タスクに、重要なイベント (マージ、破棄など) に関するコメントを自動的に残します。パッチが 2 つ以上のバグを解決する場合は、各 Bug: T12345 参照を末尾の独自の行に (1行に1個) 配置します。

Bug: T299087
Bug: T299088

相互参照

別のコミットを参照するときは常に、マージ済みのコミットの SHA-1 git ハッシュを使用します。コミットがまだ保留中のレビューの場合は、git ハッシュの代わりに Gerrit Change-Id ハッシュを使用します。これは、git ハッシュが個々のパッチセット (リベース時に変更されるため、行き止まりが生じる) に関連しているためです。

変更 ID

Gerrit の git-review ツールは、新しいコミットに「Change-Id: Ixxx」キーワードを自動的に追加します。

依存関係

Depends-On: Ixxx

クロスリポジトリ依存関係がある場合 (=コミットは別のリポジトリの別のコミットに依存している)、最後の段落に Depends-On: Ixxx... を追加することで宣言します。 (「Ixxx」... は他のコミットの Change-Id です。) これは、Zuul に当該コミットと一緒にテストするように指示します。

開発者に追加的なガイドを提供するために、他のリポジトリのコミットメッセージの最後の段落で Needed-By: Iyyy... を使用して逆方向の関係を示せます。 (「Iyyy」はあなたのコミットの Change-Id です。) Zuul はこれには反応せず、あくまで人間の読者のためにあることにご注意ください。また、Gerrit は、Depends-On の存在に基づいて自動的にバックリンクを追加します。Needed-By の有無にかかわらずです。

他の人をクレジット表示する

Co-Authored-by: gerrit_username <gerrit_user_email@example.com>

Change-id の前にこの行を追加して、変更に取り組んでいる他の開発者のクレジットを表示します。改行で区切って複数人を追加できます。

コミットメッセージのフッターの他の単語とは異なり、by は大文字ではありません。Co-Authored-By ではなく Co-Authored-by です。

参考資料

脚注

↑ This is a legacy from times when lines were provided on punched cards. Columns 1 to 72 where used for the statement and columns 73 to 80 for short comments. Size 72 is reasonable enough to understand the code at first glance.
↑ すべてのヘッダー/フッターと同様に、名前をハイフンで区切って、個別に先頭を大文字にした名前で記述します (例: Hypothetical-Header-Or-Footer)。名前の後にコロン (":") を入力し、その後に空白を 1 つ挿入します。 Git コミット、HTTP ヘッダー、メールヘッダーと同様に、フッターの上に余分な空白行を追加すると、フッターが切り捨てられ、空白行の前の部分も誤って本文と解釈されてしまいます。

[72col-1] This is a legacy from times when lines were provided on punched cards. Columns 1 to 72 where used for the statement and columns 73 to 80 for short comments. Size 72 is reasonable enough to understand the code at first glance.

[2] すべてのヘッダー/フッターと同様に、名前をハイフンで区切って、個別に先頭を大文字にした名前で記述します (例: Hypothetical-Header-Or-Footer)。名前の後にコロン (":") を入力し、その後に空白を 1 つ挿入します。 Git コミット、HTTP ヘッダー、メールヘッダーと同様に、フッターの上に余分な空白行を追加すると、フッターが切り捨てられ、空白行の前の部分も誤って本文と解釈されてしまいます。

[1]

[2]