Gerrit/コミット メッセージのガイドライン

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page Gerrit/Commit message guidelines and the translation is 100% complete.
Other languages:
English • ‎Türkçe • ‎français • ‎日本語

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

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

構造

件名

コミット メッセージの最初の行は件名として知られています。 件名は 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"。
  • 件名の末尾にピリオド (ドット) を付けないでください。
  • 必要に応じて、関連するコンポーネントを件名の前に付けます。 コンポーネントは、コミットが変更する全般的な領域です。

本文

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

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

すること:

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

してはいけないこと:

  • 他のコミットを参照する際は、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 には言及しないでください。 代わりに、本文またはフッターのメタデータで言及してください。 こうすることで、普遍的に選択、コピー、クリックできます。

コンポーネント

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

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

  • includes/ や includes/libs 配下の PHP クラスのディレクトリ ("installer", "jobqueue", "objectcache", "resourceloader", "rdbms" など)
  • PHP クラス名 ("Title", "User", "OutputPage" など)。通常、includes/ に下位ディレクトリがないクラスの場合。
  • ResourceLoader モジュール名 ("mediawiki.Title", "mediawiki.util" など)。
  • 変更の種類に関連する複数の領域に影響する汎用的なキーワード。例:
    • "build" - 開発ワークフローに関連するファイルの変更 (package.json, .travis.yml の更新など) の場合
    • "tests", "qunit", "phpunit" - 単体テストや統合テストのスイート、またはテスト スイート ランナーのみに影響する変更の場合。

Phabricator

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

コミットが (部分的にでも) 解決するか、特にバグに関連することを表現するには、コミット メッセージの末尾にあるフッターに Bug: Txxx を追加します。 [1] (コミット メッセージを修正 (amend) する場合は、Change-Id: 行のすぐ上に挿入します。Change-Id: 行との間に空白行は挿入しません。) 

Bug: T169

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

相互参照

別のコミットを参照するときは常に、マージ済みのコミットの 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 に当該コミットと一緒にテストするように指示します。

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

Co-Authored-byː gerrit_username <guerrit_user_email@example.com>

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

参考資料

脚注

  1. ↑ すべてのヘッダー/フッターと同様に、名前をハイフンで区切って、個別に先頭を大文字にした名前で記述します (例: Hypothetical-Header-Or-Footer)。 名前の後にコロン (":") を入力し、その後に空白を 1 つ挿入します。 Git コミット、HTTP ヘッダー、メール ヘッダーと同様に、フッターの上に余分な空白行を追加すると、フッターが切り捨てられ、空白行の前の部分も誤って本文と解釈されてしまいます。
方針
全般的なガイドライン
コーディング規約
API クライアント コード
草稿:
Retrieved from "https://www.mediawiki.org/w/index.php?title=Gerrit/Commit_message_guidelines/ja&oldid=4320649"