適切な CL のディスクリプションを書く

CL のディスクリプションは何が変更され、なぜ変更されたのかを説明する公式記録です。この記録はバージョン管理の履歴に永続的に残され、長期にわたって読まれます。レビュアー以外にも数百人もの人が読むこともあります。

将来の開発者はあなたの CL をディスクリプションに基づいて検索します。将来の誰かがあなたの作成した変更を見つけようとして、詳細は忘れているけれどもその変更に関するおぼろげな記憶を頼りに検索するかもしれません。重要な情報がすべてコードにだけ書かれていてディスクリプションに記載されていないと、探している CL を見つけるのが非常に難しくなるでしょう。

一行目

• 何を行っているのかを短く要約する
• 完全な文で、命令形で書く
• 次の行は空行にする

CL の一行目には、その CL が何を行っているのかを明確に記した短い要約を書いてください。二行目は空行にしてください。将来コードを検索する人はコードのバージョン管理履歴を拾い読みするのにまずこの箇所を読むことになります。そのときにあなたの CL が何をしたのか概要をつかむために CL のコードやディスクリプション全体を読まなくて済むように、一行目にしっかりと有益な情報を盛り込んでください。

慣習的に、CL のディスクリプションの一行目は完全な文で、命令のように (命令形で) 書きます。たとえば、「Deleting the FizzBuzz RPC and replacing it with the new system.」と書くのではなく「Delete the FizzBuzz RPC and replace it with the new system.」と書きます。もっとも、ディスクリプションの他の部分まで命令形で書く必要はありません。

主要部に有益な情報を盛り込む

二行目以降のディスクリプションには有益な情報を盛り込んでください。解決されている問題に関する短い説明を書くこともありますし、なぜこれが最良の方法なのかを説明することもあります。その方法に欠陥があれば、その点にも言及してください。また関連があれば、バグチケットの番号やベンチマーク結果、設計ドキュメントのリンク等の背景も書いてください。

小さな CL であっても詳細に書くよう心がける価値があります。CL をコンテキストの中に位置付けてください。

CL ディスクリプションの悪い例

「Fix bug」とだけ書いた CL ディスクリプションは情報量不足です。どんなバグでしょうか？バグを修正するために何をしたのでしょうか？他にも悪いディスクリプションの例を以下に示します。

• “Fix build.”
• “Add patch.”
• “Moving code from A to B.”
• “Phase 1.”
• “Add convenience functions.”
• “kill weird URLs.”

いくつかのものは実際にあった CL ディスクリプションです。作成者は有益な情報を提供しているつもりかもしれませんが、上の例は CL ディスクリプションの目的を果たせていません。

適切な CL ディスクリプションの例

以下は適切なディスクリプションの例です。

機能変更

rpc: RPC サーバーのメッセージフリーリストのサイズ制限を取り除く。(訳注: 英語では命令形)

FizzBuzz のようなサーバーには巨大なメッセージがあり、再利用することでメリットがある。フリーリストを大きくし、徐々にフリーリストエントリーを解放する goroutine を追加することで、アイドリング中のサーバーが最終的にすべてのフリーリストエントリーを解放するようにした。

最初の文で CL が実際に何をするのかを説明しています。以降のディスクリプションでは、解決される問題となぜこれが適切な解決なのか、また特定の実装に関する付加情報を記述しています。

リファクタリング

TimeStr と Now メソッドを使用するため Task を TimeKeeper と一緒に初期化する。(訳注: 英語では命令形)

Task に Now メソッドを追加することで、borglet() getter method を除去できるようにする (これは OOMCandidate が borglet の Now メソッドを呼び出すために使うだけだった)。これは TimeKeeper に委譲する Borglet のメソッドを置き換える。

Task に Now を与えられるようにするのは Borglet への依存をなくすための一ステップである。最終的には Task から Now を取得することに依存している部分は TimeKeeper を直接使うように変更すべきだが、これはスモールステップでリファクタリングするための調整である。

Borglet の階層構造をリファクタリングする長丁場のゴールに向けて引き続き作業する。

一行目は CL が何をするのかとどのような変更なのかを説明しています。以降のディスクリプションでは特定の実装と CL のコンテキストを説明しています。CL のソリューションは理想的ではないものの将来の方向性を示しています。またこの説明ではなぜこの変更が行われるのかにも言及しています。

コンテキストの説明が必要な小さな CL

status.py の Python3 ビルドルールを作成する (訳注: 英語では命令形)

これにより、Python3 ですでにそうしているようにこれを使用しているユーザーが自分の tree の中を探さなくても規定の status ビルドルールの隣のルールに依存できるようになる。そのことで新しいユーザーには可能なら Python2 ではなく Python3 を使用するよう促し、現在作業中の自動化されたビルドファイルのリファクタリングツールが有意に単純化される。

一文目は何が実際に行われているのかを説明しています。以降のディスクリプションではなぜその変更が行われるのかを説明し、レビュアーに十分なコンテキストを提供しています。

CL を提出する前にディスクリプションをレビューする

CL はレビューの間、重要な変更を被ることがあります。CL を提出する前に CL ディスクリプションをレビューするのが有意義な場合があります。それはディスクリプションが CL の内容を正しく反映してることを確認するためです。

次: 小さな CL