Gerrit/Commit message guidelines/ja

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

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


 * 件名の行では変更を要約します. これはリポジトリに永遠に残ることを心に留めておいてください.
 * 件名の行では命令形を使用してください. 命令形は、誰かに指示を与えているように聞こえます. "Change", "Add", "Fix", "Remove", "Update", "Refactor", "Document" などの単語で始めます. いい例は "Add Badge::query for querying the API"、"Allow zeroes in SimpleBadge::add".  悪い例は "Added Badge::query method"、"Fixed Badge::query method"、"Badge can query the API"、"Zeroes work when adding badges".
 * 件名の末尾にピリオド (ドット) を付けないでください.
 * 必要に応じて、関連するコンポーネントを件名の前に付けます. コンポーネントは、コミットが変更する全般的な領域です.

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


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

Do:


 * 本文と件名を 1 行の空行で区切ります.
 * メッセージ本文を折り返して、行が 100 文字未満になるようにします. ただし、URL を分割または折り返しをしないでください. URL が長くても保持してください.
 * "Bug" と "Change-Id" のメタデータを以下の例とまったく同じように整形し、本文の最終行の後に空行を入れた後に一緒に配置します.
 * (省略された) Git コミット ハッシュを使用して、他の (マージ済の) コミットを参照します. 必要に応じて、Gerrit Change-Id を使用して、まだマージされていないコミットを参照してください.

Don't:


 * 他のコミットを参照する際は、Gerrit URL を使用せず、代わりに Git コミット ハッシュを使用してください. これにより、オフライン時に Git リポジトリ内で簡単に遷移できます.  さらに、すべてのリポジトリ ビューアー (Gerrit、Gitiles、Phabricator、GitHub、ローカル Git インターフェイス) の利用者が、同じインターフェイス内の他のコミットに自動的に移動できるようになります.  URL は、オンラインでかつ Gerrit を使用している場合にのみ解決できるため、人々はすばやく遷移できなくなります.
 * 変更の唯一の説明として URL を使用しないでください. 変更が他の場所での議論または外部の説明文書によって正当化される場合は、コミット メッセージの関連するポイントを簡潔に要約します.

いい例
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

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


 * Gerrit は件名を、メール通知、IRC 通知、検索結果で使用します.
 * GitHub は件名を以下で使用します: コミット履歴, コミットの件名.
 * Git CLI (コマンドライン インターフェイス) は件名を以下で使用します:,  ,  ,  , etc.
 * その他多数
 * その他多数

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

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


 * や  配下の PHP クラスのディレクトリ ("installer", "jobqueue", "objectcache", "resourceloader", "rdbms" など)
 * PHP クラス名 ("Title", "User", "OutputPage" など). 通常、 に下位ディレクトリがないクラスの場合.
 * ResourceLoader モジュール名 ("mediawiki.Title", "mediawiki.util" など).
 * Generic keyword affecting multiple areas relating to the type of change, such as:
 * "build" - 開発ワークフローに関連するファイルの変更 (,  の更新など) の場合
 * "tests", "qunit", "phpunit" - 単体テストや統合テストのスイート、またはテスト スイート ランナーのみに影響する変更の場合.

Phabricator
To reference a bug or task, in the commit message mention it inline using the Txxx notation (e.g. " That was caused by T169. ")

To express that a commit resolves (even partially) or is specially relevant to a bug, add  in the footer at the end of the commit message. (If you're amending a commit message, insert it immediately above the  line, without an empty line between them.)

Bug: T169

A bot will automatically leave a comment on the Phabricator task about any significant events (being merged, abandoned, etc.). If a patch resolves two or more bugs, put each  reference on its own line at the bottom.

相互参照
Whenever you refer to another commit, use the SHA-1 git hash of the merged commit. If the commit in still pending review, use the Gerrit Change-Id hash instead of the git hash because the hash relates to an individual patch set (which changes when rebased, thus creating a dead-end).

変更 ID
's  tool will automatically append the "Change-Id: Ixxx" keyword to new commits.

依存関係
If you have cross-repo dependencies (your commit depends on another commit in a different repository), declare them by adding  to the last paragraph. ("Ixxx"... is the  of the other commit.) This will instruct Zuul to test the commit together with that one.

参考資料

 * Node.js Commit Guidelines
 * Git Core Commit Guidelines
 * jQuery Commit Guidelines
 * Erlang Commit Guidelines
 * A Note About Git Commit Messages - by Tim Pope
 * How to Write a Git Commit Message - by Chris Beams
 * A Note About Git Commit Messages - by Tim Pope
 * How to Write a Git Commit Message - by Chris Beams