🌾 🤯 💇🏼 記事の翻訳：OpenStackからGitコミットを作成するためのベストプラクティス ✂️ 🏴 🙎🏿

「Habrahabr」の読者に、記事「OpenStackからコミットを伝えるためのグッドプラクティス」の翻訳を提供します。

1 Git Commitベストプラクティス

以下のドキュメントは、libvirt、QEMU、OpenStack Novaなど、Gitを使用する多くのプロジェクトでのコード開発経験、バグ修正、およびコードレビューに基づいています。 Kernel、CoreUtils、GNULIBなど、他のオープンソースプロジェクトを考慮すると、それらはすべてかなり一般的な慣行に従うことが示唆されています。これは、Nova Gitストーリーの品質を改善したいという願望に基づいています。品質は、開発における定義の抽象的な用語です。ある人にとって特定のコードが「Thing of Beauty」である場合-別の人にとっては「松葉杖」（Evil Hack）です。それでも、OpenStackのプロジェクトとマージするためにGitコミットを送信する際に、どのように、何をすべきか、または逆に何をすべきでないかについて、いくつかの一般的な推奨事項を策定できます。

このトピックは2つの領域に分けることができます。

複数のコミットに結合または分割する手順
コミットメッセージの情報

内容

1 Git Commitベストプラクティス

1.1概要

このドキュメントで説明する考えと例は、変更を連続したコミットのグループに分割することの重要性と、それらに適切なメッセージを書き込むことの重要性を明確に示す必要があります。これらの手順が広く適用される場合、これによりOpenStackのgit履歴の品質が大幅に向上します。 gitの履歴を効果的に変更するには、ニンジンとスティックが必要です。この文書はニンジンである必要があり、利点と利点に人々の注意を引き付けますが、他の人にとっては、Gerrit Collective Code Inspection Systemの使用は鞭のように振る舞います。 ;-P

言い換えれば、Gerritで検査するとき、コードの正確さだけを見る必要はありません。検査するときは、まずコミットメッセージを調べて、メッセージ自体の改善を示す必要があります。多くの論理的な変更を結合し、送信者がそれらを別々のコミットに分割することを必要とするコミットを詳しく調べてください。インデントのフォーマットの変更が機能の変更と組み合わされていないことを確認してください。また、コードのリファクタリングが機能の変更などとは別に修正されるようにしてください。

Gerritの一連のパッチの処理が完全に理想的ではないことにも言及する価値があります。ただし、一連のパッチの作成を避けるために、これを正当な理由と見なすべきではありません。使用するツールは開発者のニーズに対応する必要があります。また、それらはオープンソースであるため、修正または改善できます。ソースコードは「よく読まれ、時々書かれます」。したがって、最も重要な基準は、コミュニティの多数の開発者の助けを借りてコードの長期サポートを改善することです。もう一度コード。

そして今、詳細な原則だけでなく、良い習慣と悪い習慣の例も。

1.2変更の構造的な分離

適切なコミットを作成するための基本的なルールは、コミットごとに「論理変更」を1つだけ提供することです。この重要なルールには多くの理由があります。

コードの変更が少ないほど、潜在的な弱点のチェックと特定がより迅速かつ容易になります。
コミットが正しくないか壊れていることが判明した場合、不正なコミットがロールバックされる可能性があります。また、元のコミットと混同するコードに他の無関係な変更がなければ、それははるかに簡単になります。
git bisectコマンドを使用するなどのトラブルシューティングを行う場合、小規模で整形式のコミットは、コード内で問題が発生した場所と時期を特定するのに役立ちます。
git annotateまたはgit blameでgitの履歴を表示するとき、小さな整形式のコミットは、コードの問題部分を見つけて切り分け、問題の断片がどこから来たのかを理解するのに役立ちます。

1.2.1コミットを作成する際に避けるべきこと

悪い習慣の一般的な例を知り、理解する必要があります：

フォーマットのインデントとスペースをコードの機能的な変更と組み合わせます。

変更をフォーマットすると、重要な機能の変更があいまいになり、レビューアがコミットの正確さを正確に判断することが難しくなります。 解決策： 2つのコミットを作成します。1つはフォーマットの変更、もう1つは機能の変更です。通常、インデントが最初に行われますが、これは厳密な規則ではありません。

2つの無関係な機能変更を混合します。

繰り返しますが、レビュアーは、2つの無関係な変更を混在させると、欠陥を特定することがより難しくなります。壊れたコミットを後でロールバックする必要がある場合は、2つの無関係な変更を見つけて解決する必要がありますが、新しいエラーが発生するリスクもあります。

1つの巨大なコミットで優れた新機能を送信します。

新しい関数のコードは、実装全体が存在する場合にのみ有用である可能性があります。ただし、これは、1回のコミットで機能全体を提供する必要があるという意味ではありません。多くの場合、新機能は既存のコードのリファクタリングを伴います。新しい関数が実装されているコミットではなく、個別のコミットでリファクタリングを実行することが非常に望ましいです。これは、リファクタリングに意図しない機能変更がないことをレビューアーとテストスイートが確認するのに役立ちます。最近書かれたコードでさえ、多くの場合、独立して考慮できるいくつかの部分に分割できます。たとえば、新しい内部APIまたはクラスを追加する変更は、個別のコミットで行うことができます。繰り返しますが、これによりコード検証が容易になります。また、新しい機能をマージする準備ができていない場合、他の開発者がgit cherry-pickを使用して作業の小さな塊を取得できるようにします。新しいパブリックHTTP APIまたはRPCインターフェイスの追加は、実際の内部実装とは別のコミットで行う必要があります。これにより、作成者とレビュー担当者は、現在選択されている内部実装にとって簡単な設計を選択するだけでなく、APIまたはRPCの全体的な設計について考えるようになります。パッチがパブリックHTTPに影響する場合は、APIImpactフラグを使用します（外部リンクの有効化を参照）。

従うべき主なものはルールです：

, . - . .

1.2.2悪い習慣

それでは、Git Novaの歴史からいくつかの例を示しましょう。注：コミットハッシュは参照用に引用されていますが、著者の名前は削除されています。1人の人を責めたり、怒らせたりしないでください。時々、私たちはそれぞれ、良い形の規則を破ったことを責めるべきです。さらに、これらのコミットをレビューして承認した人は、それらを作成して送信した人と同じように有罪です。

1.2.2.1例1

 : ae878fc8b9761d099a4145617e4a48cbeb390623 : [] : . 1  01:44:02 2012 . +0000    create libvirt *       create *   wait_for_destroy    undefine *        *  reset     create / destroy *  resume_host_state     hard_reboot *  rescue/unrescue        Change-Id: I2072f93ad6c889d534b04009671147af653048e7

このコミットにより、少なくとも2つの独立した変更が行われました。

hard_rebootメソッドで新しいリセットAPIを使用するように切り替える
「hard_reboot」を使用しないように内部ドライバーメソッドを修正

ここでの問題は何ですか：

まず、これらの変更を同時に（1回のコミットで）行う必要がある理由はありません。最初のコミットには、hard_rebootメソッドのさまざまな場所で呼び出しを終了する変更が含まれる場合があります。 2番目のコミットは、hard_rebootの実装を上書きする可能性があります。
第二に、reset libvirtメソッドの使用への移行は、大規模なコードリファクタリングで隠されていたため、レビュー担当者は見逃していました。このコミットはすぐに問題になることがわかりましたが、無関係な変更が多数あるため、些細なロールバックは不可能です。

1.2.2.2例2

 : e0540dfed1c1276106105aea8d5765356961ef3d : [] : C. 16  15:17:53 2012 +0400  lvm-disk-images     LVM   VM.   LVM    libvirt. VM-     LVM      `libvirt_images_volume_group`.   `libvirt_local_images_type` ,     .  : `raw`, `lvm`, `qcow2`, `default`.  `libvirt_local_images_type` = `default`,     `use_cow_images`.   `libvirt_sparse_logical_volumes`  ,       (   virtualsize        ).       `False`.     : `Raw`, `Qcow2`  `Lvm`.      ,      `LibvirtConnection._cache_image` ` libvirt_info`      `LibvirtGuestConfigDisk`  libvirt.  `Backend` ,     . Change-id: I0d01cb7d2fd67de2565b8d45d34f7846ad4112c2

この変更により、1つの新しい主要な機能が導入されるため、一見、単一のコミットを使用するのが合理的と思われますが、パッチを見ると、新しいLVM機能による大量のコードリファクタリングが含まれているため、明らかに非常に混乱しています。この事実により、QCow2 / Raw画像のサポートにより、可能性のある回帰を特定することが難しくなります。少なくとも4つの別々のコミットに分割する必要があります。

use_cow_images構成フラグは、廃止されたuse_cow_imagesフラグの後方互換性をサポートする新しいlibvirt_local_images_typeフラグに置き換えられました。
内部クラス「Image」の作成とRawおよびQCow2のサブクラスの実装。
新しいImageクラスを呼び出して、raw / qcow2イメージ管理コードを置き換えるlibvirtドライバーをリファクタリングします。
LVMイメージクラスの新しい実装の紹介。

1.2.3グッドプラクティスの例

1.2.3.1例1

 : 3114a97ba188895daff4a3d337b2c73855d4632d : [] : . 11  17:16:10 2012 +0100      KVM  VM  PIT  RTC : 573ada525b8a7384398a8d7d5f094f343555df56 : [] : . 1  17:09:32 2012 + 0100       VM libvirt

これら2つの変更により、ゲストKVMタイマーの構成がサポートされます。 libvirt XML構成を作成するための新しいAPIの実装は、新しいAPIを作成するためのKVMゲストポリシーの変更から明確に分離されました。

1.2.3.2例2

 : 62bea64940cf629829e2945255cc34903f310115 : [] : . 1  14:49:42 2012 -0400     rpc.queue_get_for(). Change-Id: Ifa7d648e9b33ad2416236dc6966527c257baaf88 : cf2b87347cd801112f89552a78efabb92a63bac6 : [] : . 30  14:57:03 2012 -0400   shared_storage_test   rpcapi. ......  get_instance_disk_info    rpcapi. ......  remove_volume_connection    rpcapi. ......  compare_cpu    rpcapi. ......  get_console_topic()    rpcapi. ......  refresh_provider_fw_rules()    rpcapi. ...    ...

このコミットシーケンスにより、プラグインメッセージング実装を使用できるように、OpenStack Compute（Nova）内のRPC APIレイヤー全体が再編成されました。機能の主要部分のこのような重要な変更の重要なポイントは、作業を大きなコミットシーケンスに分割することでした。これにより、意味のあるコードチェックが可能になり、プロセスの各段階で変更の追跡と可能な回帰の検索が簡素化されました。

1.3コミットメッセージの情報

コミットメッセージのテキストは、コード自体が変わるのと同じくらい重要です。メッセージを作成するとき、留意すべき重要なことがいくつかあります。

レビューアが最初から問題が何であるかを理解していると思い込まないでください。

バグレポートといくつかのコメントを読んだとしても、問題が何であるかが常に明確ではないことがよくあります。コミットメッセージには、元の問題の明確な説明を含める必要があります。特定のバグは、問題の特定方法に関する興味深い歴史的背景にすぎません。レビューアは、エラー追跡システムでこの欠陥を調査することなく、提案されたパッチが正しい決定を行うために何を行うかを理解する必要があります。

レビューアが外部のWebサービスまたはサイトにアクセスできると想定しないでください。

6か月後、電車/飛行機/バス/ビーチ/バーに乗っている人が問題を修正してgitの履歴を表示すると、オンラインエラーレポートまたはドキュメントを使用してサーバーにアクセスできる保証はありません。分散ソースコード管理（SCM）システムは、リポジトリ内のすべての情報にアクセスするためにオンラインである必要がなくなったという点で、大きな一歩を踏み出しました。コミットメッセージは、gitのメリットを享受し続けるために、完全に自給自足でなければなりません。

コードが自明/自己文書化であると想定しないでください。

ある人にとって明らかなことは、別の人にとって完全に理解できない場合があります。もちろん、明らかな誤字や書式の変更を修正する場合を除き、変更ごとに、元の問題の内容と修正方法を常に文書化します。

変更が行われた理由を説明してください 。

よくある間違いは、開発者がこのように決定した理由を説明せずに、コードの記述方法を単に説明することです。最も重要なことは、変更の意図と動機を説明することですが、コードの一般的な構造を説明することも忘れないでください。

コミットメッセージを読んで、コード構造の改善を示しているかどうかを確認します。

多くの場合、大きなメッセージを説明するとき、変更を2つ以上の部分に分割する必要があることが明らかになります。戻って複数のコミットに分割することを恐れないでください。

何をチェックするかを適切に決定するために十分な情報を提供します。

Gerritが新しいパッチパッチに関する電子メールアラートを送信すると、電子メールには最小限の情報、主にコミットメッセージと変更されたファイルのリストが含まれます。大量のパッチがあるため、すべてのレビュー担当者がパッチを詳細に調査することを期待しないでください。したがって、コミットメッセージには、これが見なければならないパッチであることを潜在的なレビューアに警告するのに十分な情報を含める必要があります。

コミットの最初の行が最も重要です。

Gitでは、コミットメッセージの最初の行には特別な意味があります。ブランチや、テキスト用のスペースがあまりない他の多くの場所をマージするときに、git annotateチームのメッセージ、gitkビューアプログラムで電子メールの件名として使用されます。変更自体の簡単な説明に加えて、影響を受けるコードの量を忘れないでください。たとえば、これがlibvirtドライバーに影響する場合、最初の行のどこかに「libvirt」を指定します。

現在のコードの制限を説明します。

変更中のコードに将来の機能拡張や既知の制限がある可能性がある場合は、コミットメッセージでそれらを必ず記載してください。これは、著者がより広い視野を検討し、長期的な欲求と比較した短期的な目標に関してどのような妥協が行われたかをレビューアに示しています。

このパッチに固有のコメントを含めないでください。

つまり、コミットをやり直す場合は、メッセージに「パッチセット2：リベース」を追加しないでください。変更をマージしても、違いは生じません。ただし、変更に関するコメントとしてGerritにメモを書きます。これは、レビュー担当者がパッチセット間で何が変更されたかを見つけるのに役立ちます。これは、「追加された単体テスト」、「修正されたローカリゼーションの問題」、またはコミットの全体的な目的に影響を与えないその他のパッチなどのコメントにも適用されます。

従うべき主なものはルールです：

, . - . .

1.3.1外部リンクの包含

メッセージは主に人間による解釈を目的としていますが、常にマシン処理を目的としたメタデータが含まれています。 OpenStackでは、「Change-Id」に加えて、バグ識別子へのオプションリンク、ブループリント（スキーマ/ドキュメント）へのリンク、DocImpactフラグ、APIImpactフラグ、およびSecurityImpactフラグが含まれます。

「Change-Id」行は、Gitフックによって生成される変更を記述する一意のハッシュです。 rebaseコマンドでコミットを編集する場合、検査後に変更されるべきではありません。また、パッチバージョンを追跡するためにGerritによって使用されます。
文字列 'bug'は、いくつかの方法でエラーを参照できます。レビュー担当者がLaunchpadでエラーにすばやくアクセスできるように、Gerritはreview.openstack.orgのパッチを表示するときにエラーリンクを作成します。
- Closes-Bug：＃1234567-コミットが参照しているエラーを完全に排除して閉じることを意図している場合は、「Closes-Bug」を使用します。
- 部分バグ：＃1234567-コミットが部分的な修正であり、このバグを修正するためにさらに作業が必要な場合は、「部分バグ」を使用します。
- Related-Bug：＃1234567-コミットが指定されたエラーに単に関連している場合は、 'Related-Bug'を使用します。
コミットが特定の機能を実装することを意図している場合、行「blueprint」は、Launchpad blueprint（Launchpad Webサイトの文書）という名前を示す必要があります。レビュー担当者がLaunchpadのドキュメントにすばやくアクセスできるように、Gerritはreview.openstack.orgでパッチを表示するときにブループリントへのリンクを作成します。
DocImpact行には、 DocImpact行と、この変更がドキュメントに影響する理由に関するコメントが含まれています。 DocImpactを別の行に配置します。レビュー担当者が変更の理由を理解できるように、このフラグを使用して、ドキュメントがパッチに含まれているか、変更がドキュメントに影響することを示します。できるだけ多くの情報を含めてください。このフラグがコミットメッセージに含まれると、Gerritはopenstack-manualsプロジェクトのバグレポート（openstack命令）を作成して、実行を追跡およびシーケンスするか、必要に応じてopenstack-api-siteに移動します。
APIImpact行には、 APIImpact行と、この変更がパブリックHTTP APIに影響する理由に関するコメントが含まれています。 APIImpactを別の行に配置します。このフラグを使用して、パッチがパブリックHTTP APIを作成、更新、削除するか、パブリックAPIの動作を変更することを示します。できるだけ多くの情報を含めてください。このフラグがコミットメッセージに含まれている場合、関連するすべてのレビューはこのリンクを使用して見つけることができ、 API_Working_Groupドキュメントのページも関連するレビューを見つけるのに役立ちます。さらに、Freenode ＃openstack-sdksチャネルの IRCを介してAPIワーキンググループに直接連絡できます。
SecurityImpact文字列には、単にSecurityImpact文字列が含まれます。変更がセキュリティに影響するため、OpenStack Security Groupによるレビューが必要であることを示すために使用されます。
UpgradeImpact行には、 UpgradeImpact行と、この変更が更新に影響する理由に関するコメントが含まれています。これは、変更が継続的な展開、またはNからN + 1への更新を行っているユーザーのアップグレードの結果であることを示すために使用されます。また、影響を受けるプロジェクトのリリースノートのアップグレードノートセクションへの更新を示す場合もあります。

すべてのメタデータはマシン用であり、人々にとって二次的な重要性があるため、コミットメッセージの最後にすべてのメタデータをグループ化する必要があります。

注：Gitを使用する多くのオープンソースプロジェクトでは、「Signed-off-by」タグ（「git commit -s」コマンドを使用して生成される）を含めるのが一般的ですが、これはOpenStackには不要です。コードをGerritに送信する前に、OpenStackはすべてのメンバーがCLA（Contributor License Agreement）に署名することを要求します。これは同等の目的を果たします。

特定のパッチに取り組んだ人々を示すために、コミットメッセージでname-name@example.com （ Collaboration ）のCo-Authored-Byを使用することをお勧めします。これは複数の著者の承認に関する合意であり、私たちのプロジェクトは、統計収集ツールがそれらを分析する際にこれらのフィールドを監視することを奨励しています。

1.3.2コミットメッセージの構造の概要

最初の行に、変更の簡単な説明を入力します。
最初の行の後に空の行を挿入します。
次の行に、変更の詳細な説明を書き、必要に応じて分類します。
最初の行は50文字に制限する必要があり、ピリオドで終了しないでください。
後続の行は72文字で囲む必要があります。
- vim（ほとんどのディストリビューションの$ EDITOR環境変数のデフォルト）は、自動的に文字列をラップできます。ほとんどの場合、vimrcサンプルファイル（ /usr/share/vim/vim74/vimrc_example.vim
  
  ）を~/.vimrc
  
  にコピーするだけです。
- 段落を編集した後、エスケープキーを押して、段落内にカーソルを置き、組み合わせgqip
  
  を入力することで、段落をラップできます。
必要に応じて、「Change-id」、「Closes-Bug #NNNNN」、「blueprint NNNNNNNNNNNN」の行を最後に配置します。

例：

   libvirt get_cpu_info    API  get_cpu_info   libvirt      XPath      XML .       LibvirtConfigCaps.        . DocImpact Closes-Bug: #1003373 Implements: blueprint libvirt-xml-cpu-model Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

1.3.3悪い習慣の例

Git Novaの歴史からいくつかの例を見てみましょう。著者の名前も削除されています。だれも非難したり怒らせたりしたくないので。

1.3.3.1例1

 : 468e64d019f51d364afb30b0eed2ad09483e0b98 : [] : . 18  16:07:37 2012 -0400     compute/utils.py Fixes bug #1014829

問題：インポートされることになっていたもの、このインポートでは不十分な場所、およびなぜ必要なのかについては言及されていません。この情報はバグ追跡ツールに含まれており、自己完結型の説明を提供するためにコミットメッセージにコピーする必要がありました。例：

    "exception"  compute/utils.py nova/compute/utils.py      exception.NotFound,     .

1.3.3.2例2

 : 2020fba6731634319a0d541168fbf45138825357 : [] : . 15  11:12:45 2012 -0600    ec2id     Fixes bug #1013765 *      ec2utils.id_to_ec2_id() Change-Id: I5e574f8e60d091ef8862ad814e2c8ab993daa366

問題：現在の（間違った）形式の何が間違っているのか、または新しい固定形式が何であるのかについては言及していません。この情報はエラートラッカーでも利用可能であり、コミットメッセージに含める必要があります。さらに、このエラーは以前の変更によって引き起こされたリグレッションを修正しましたが、以前に何が起こったかについては言及されていません。例：

    ec2id        uuid' ,    XXXXXXX,   ec2               (i-xxxxx).      vol-xxx  snap-xxxx.      ec2utils.id_to_ec2_id () Fixes bug #1013765

1.3.3.3例3

 : f28731c1941e57b776b519783b0337e52e1484ab : [] : . 13  10:11:04 2012 -0400     libvirt. Fixes LP bug #1012689 Change-Id: I91c0b7c41804b2b25026cbe672b9210c305dc29b

問題：このコミットでは、メッセージは単に何が行われたかを記録するだけで、なぜ行われたのかを記録しません。以前に一連の変更によりlibvirtの新しい最小バージョンが導入されたことに言及する価値がありました。検証が失敗した場合、現在の動作を報告することも必要でした。

例：

    libvirt,  0.9.7   XXXXXXXX   API  'reset'     libvirt 0.9.7  .     libvirt  ,     .     ,   . Fixes LP bug #1012689 Change-Id: I91c0b7c41804b2b25026cbe672b9210c305dc29b

1.3.4グッドプラクティスの例

1.3.4.1例1

 : 3114a97ba188895daff4a3d337b2c73855d4632d : [] : . 17  17:16:10 2012 +0100      KVM  VM  PIT  RTC      PIT  RTC    KVM     ()    .  ,  Windows 7       KVM  ,    Linux      .  PIT ,        , ..    RTC  ,        ,    ''    libvirt XML <clock offset='utc'> <timer name='pit' tickpolicy='delay'/> <timer name='rtc' tickpolicy='catchup'/> </clock>   KVM   -no-kvm-pit-reinjection -rtc base=utc,driftfix=slew     ,       .              Closes-Bug: #1011848 Change-Id: Iafb0e2192b5f3c05b6395ffdfa14f86a98ce3d1f

, :

, ( KVM )
( PIT / RTC)
( XML / QEMU args)
( )
Closes-Bug

1.3.4.2 2

 : 31336b35b4604f70150d0073d77dbf63b9bf7598 : [] : . 06  22:45:25 2012 -0400      CPU   ,      ,      ARM    X86_64  .         ,     .  libvirt            permitted_instances_types   cpu_info .  Xen     .         permitted_instances_types     .   ARM     .   ArchFilter  . Change-Id: I17bd103f00c25d6006a421252c9c8dcfd2d2c49b

, :

, ( )
( )
( libvirt )
(, Xen)

記事の翻訳：OpenStackからGitコミットを作成するためのベストプラクティス