良いCLの説明文を書く

CLの説明文は、何が変更されているのかと、なぜその変更が行われたのかを公に記録するものです。これは、バージョン管理の履歴の一部となり、レビュワー以外の数百人の人々によって何年もの間読まれる可能性があります。

将来の開発者は、説明文に基づいてCLを検索するでしょう。将来の誰かが、関連性のある変更のかすかな記憶を持っているが、具体的な情報が手元にないために、あなたの変更を探しているかもしれません。重要な情報がコードではなく説明文にある場合、彼らがあなたのCLを見つけるのはずっと難しくなります。

最初の行

• 行われていることの短い要約。
• 命令として書かれた完全な文。
• 空行で区切る。

CLの説明の最初の行は、具体的にCLによって何が行われているかの短い要約である。その後に空行を置く。これはバージョン管理の履歴の要約に表示されるため、将来のコード検索者があなたのCLやその説明全体を読まなくても、実際にCLが何をしたのか、他のCLとどのように異なるのかを理解するのに十分な情報であるべきです。つまり、最初の行は単独で成立し、読者がコードの履歴をスキャンするのをはるかに速くすることができるようにする必要があります。

最初の行を短く、焦点を絞り、要点に留めるようにしてください。読者への明確さと有用性が最優先です。

伝統的に、CLの説明の最初の行は、命令文（命令文）として書かれた完全な文です。例えば、「FizzBuzz RPCを削除し、新しいシステムで置き換える」と言う代わりに、「FizzBuzz RPCを削除して新しいシステムで置き換える」と書きます。ただし、説明の残りを命令文として書く必要はありません。

本文は情報提供です

最初の行は短く、焦点を絞った要約であるべきです。その他の説明では、変更リストを全体的に理解するために読者が必要とする補足情報や詳細を含めるべきです。解決されている問題の簡単な説明や、なぜこれが最善のアプローチなのかを含めることがあります。アプローチの欠点がある場合は、それも述べるべきです。関連する場合、バグ番号やベンチマーク結果、設計文書へのリンクなどの背景情報も含めることができます。

外部リソースへのリンクを含める場合、アクセス制限や保持ポリシーにより将来の読者には表示されない可能性があることを考慮してください。可能な限り、レビュワーや将来の読者がCLを理解するための十分な文脈を含めてください。

小さなCLでも細部に注意を払う価値があります。CLを文脈に置いてください。

不適切なCLの説明

「バグを修正する」というCLの説明は不十分です。どのバグですか？それを修正するために何をしましたか？ 同様に不適切な説明には以下のものがあります：

• 「ビルドを修正する」
• 「パッチを追加する」
• 「コードをAからBに移動する」
• 「フェーズ1」
• 「便利な関数を追加する」
• 「奇妙なURLを削除する」

これらのいくつかは実際のCLの説明です。短いですが、十分な有用な情報を提供していません。

良いCLの説明例

以下に、良い説明の例をいくつか示します。

機能変更

例：

RPC: RPCサーバーメッセージフリーリストのサイズ制限を削除します。

FizzBuzzのようなサーバーは非常に大きなメッセージを持っており、再利用することで利益を得ることができます。 フリーリストを大きくし、フリーリストのエントリを時間をかけて解放するゴルーチンを追加します。 これにより、アイドル状態のサーバーは最終的にすべてのフリーリストエントリを解放します。

最初の数語でCLが実際に何をするのかを説明します。残りの説明では、解決される問題、これがなぜ良い解決策なのか、そして具体的な実装についてもう少し情報を話します。

リファクタリング

例：

タスクを構築し、そのTimeStrメソッドとNowメソッドを使用するために、TimeKeeperを使用します。

タスクにNowメソッドを追加し、borglet()のゲッターメソッドを削除します（これは、OOMCandidateがborgletのNowメソッドを呼び出すためにのみ使用されていました）。これにより、Borgletに委譲するメソッドが置き換えられます。

タスクがNowを提供できるようにすることは、Borgletへの依存を排除するための一歩です。最終的には、タスクからNowを取得する依存関係を直接TimeKeeperを使用するように変更する必要がありますが、これはリファクタリングを段階的に行うための配慮です。

Borgletの階層を長期的にリファクタリングする目標を続けます。

最初の行は、CLが何を行い、これが過去からの変更であることを説明しています。説明の残りの部分は、具体的な実装、CLの文脈、解決策が理想的ではないこと、および将来の方向性について説明しています。また、なぜこの変更が行われるのかも説明しています。

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

例：

status.pyのためのPython3のビルドルールを作成します。

これにより、既にPython3を使用しているコンシューマーは、元のstatusのビルドルールの隣にあるルールに依存することができます。これは、自分自身のツリーのどこかではなく、元のビルドルールの隣に依存することを意味します。これにより、新しいコンシューマーは、可能な限りPython3を使用することが奨励され、現在作業中のいくつかの自動ビルドファイルのリファクタリングツールが大幅に簡素化されます。

最初の文は実際に何が行われているかを説明しています。残りの説明は、変更がなぜ行われているのかを説明し、レビュアーに多くの文脈を提供します。

タグの使用

タグは手動で入力されるラベルであり、CL（変更リスト）を分類するために使用できます。これらはツールによってサポートされる場合もありますし、チームの慣習として使用される場合もあります。

例：

• "[tag]"
• "[a longer tag]"
• "#tag"
• "tag:"

タグの使用は任意です。

タグを追加する際には、CLの説明の本文または最初の行に配置するかどうかを考慮してください。最初の行でのタグの使用は、内容をわかりにくくする可能性があるため、制限してください。

タグの使用例（タグありとタグなし）：

// タグは最初の行に短く保つ場合は問題ありません。
[banana] バナナを食べる前に皮をむいてください。

// タグはコンテンツ内にインラインで配置することもできます。
バナナを食べる前に #banana をむいてください。

// タグは任意です。
バナナを食べる前に皮をむいてください。

// タグが短く保たれている場合、複数のタグを使用することもできます。
#banana #apple: 果物のかごを組み立てる。

// タグはCLの説明のどこにでも配置できます。
> 果物のかごを組み立てる。
>
> #banana #apple

// タグが多すぎる（または長すぎる）と最初の行が混雑します。
//
// 代わりに、タグを説明の本文に移動したり、短縮したりできるかどうかを検討してください。
[banana peeler factory factory][apple picking service] 果物のかごを組み立てる。

生成されたCLの説明

一部のCLはツールによって生成されます。できる限り、その説明もここでのアドバイスに従うべきです。つまり、最初の行は短く、焦点を絞り、単独で成立し、CLの説明本文には、レビュワーや将来のコード検索者が各CLの効果を理解するのに役立つ情報を含めるべきです。

CLを提出する前に説明を確認してください

CLはレビュー中に大きな変更が加えられることがあります。CLを提出する前に、CLの説明を再確認して、説明がCLの内容を正確に反映していることを確認することが価値があります。

次: 小さなCL