※本記事は、Bardによる意訳+翻訳を活用し、レイアウト調整したものです。
※感想は、オリジナルです。
原文
How to Create Small Yet Powerful Pull Requests - DEV Community
意訳+要約
小さくても強力なプル・リクエストを作成する方法
小さなプルリクエストの利点
- レビューが容易になる
- コミット履歴が整理される
- バグや競合のリスクが低くなる
小さなプルリクエストを作成する 5 つのヒント
- 問題をよく読んで、何を修正する必要があるかを理解する
- タスク リストを作成し、各タスクを個別のコミットに分割する
- プルリクエストを問題にリンクする
- 個別のブランチを作成する
- マージするための具体的な指示を記述する
まとめ
小さなプルリクエストは、レビューが容易で、コミット履歴が整理され、バグや競合のリスクが低くなるという利点があります。これらの利点を享受するために、上記のヒントに従って、小さなプルリクエストを作成することをお勧めします。
特に重要な部分は、以下のとおりです。
- プルリクエストのサイズは、レビューのしやすさ、コミット履歴の整理、バグや競合のリスクの低減に影響する。
- 小さなプルリクエストを作成するには、問題をよく読んで、タスク リストを作成し、個別のブランチを作成し、マージするための具体的な指示を記述する。
Bardさんに聞いてみた
Ｑ：プルリクエストを作る際、含めるべき情報は、何がありますか？
ドキュメントには、プルリクエストに含めるべき情報は記載されていません。
プルリクエストに含めるべき情報は、プロジェクトやチームによって異なります。一般的には、以下の情報が含まれます。
- プルリクエストのタイトルと説明
- 変更内容の概要
- 変更内容の詳細
- テスト結果
- マージするための指示
また、プルリクエストを作成した理由や、変更内容がプロジェクトにどのように貢献するかを説明することも重要です。
プルリクエストを作成する際には、プロジェクトのガイドラインを参照してください。
Ｑ：レビューする人は、どのようなことに気をつければいいでしょうか？
この質問については、ブログ記事では具体的に触れられていませんが、一般的にレビューする際には以下の点に注意するとよいでしょう。
- 変更内容が意図通りに機能しているかを確認する。
- 変更内容が既存のコードと競合していないかを確認する。
- 変更内容がテスト済みであることを確認する。
- 変更内容がプロジェクトのガイドラインに準拠していることを確認する。
また、レビューする際には、プルリクエストの作成者とのコミュニケーションが重要です。不明な点や懸念点があれば、積極的に質問しましょう。
具体的には、以下の点について確認するとよいでしょう。
- 変更内容の目的は何ですか？
- 変更内容はどのように実装されていますか？
- 変更内容が意図通りに機能するか、テスト結果を教えてください。
- 変更内容が既存のコードと競合する可能性はありますか？
- 変更内容がプロジェクトのガイドラインに準拠していますか？
レビューを通し、プルリクエストをより良いものにしましょう。
なお、このブログ記事では、小さなプルリクエストの作成方法について説明されています。小さなプルリクエストは、レビューが容易で、コミット履歴が整理され、バグや競合のリスクが低くなるという利点があります。これらの利点を享受するために、上記のヒントに従って、小さなプルリクエストを作成することをお勧めします。
Ｑ：プルリクエストで書くコメントのおすすめのフォーマットがあれば提案してください
プルリクエストで書くコメントのおすすめのフォーマットは、以下のとおりです。
### コメントの種類 **変更内容の概要** **変更内容の詳細** **質問や懸念点** **レビュー者への指示**
コメントの種類
まず、コメントの種類を明確にします。変更内容の確認、テスト結果の確認、コードの改善提案など、コメントの目的によって、適切なコメントの種類を使い分けましょう。
変更内容の概要
次に、変更内容の概要を簡潔に説明します。変更内容がどのようなものなのか、一目でわかるようにしましょう。
変更内容の詳細
変更内容の詳細を説明します。変更内容の目的、実装方法、テスト結果など、必要な情報をすべて記載しましょう。
質問や懸念点
不明な点や懸念点があれば、質問や懸念点を記載します。レビュー者からの回答を待つことで、プルリクエストをより良いものにすることができます。
レビュー者への指示
レビュー者への指示があれば、記載します。たとえば、テストを追加してほしい、コードを改善してほしいなどの指示を記載しましょう。
このフォーマットを参考に、わかりやすく、適切なコメントを書くようにしましょう。
また、コメントを書く際には、以下の点に注意しましょう。
- 具体的な指示を記載する。
- 感情的な表現を避ける。
- 攻撃的な言葉遣いを避ける。
具体的な指示を記載することで、レビュー者がより効果的にレビューを行うことができます。また、感情的な表現や攻撃的な言葉遣いは、レビュー者のモチベーションを下げ、レビューの質を低下させる可能性があります。
プルリクエストのレビューは、チームワークの重要な要素です。わかりやすく、適切なコメントを書くことで、レビューを円滑に進め、より良いコードを作成しましょう。
感想＋雑記
gitに限った話ではないから、SVN使うにしろ、何かしらのVCS使う場合は、気をつけるべきだと感じた。
基本的に、プルリクエストは、単位を気にするようにしている。
分割したせいで、システムが機能しなくなるようなコミットはしないようにしている。
どっちかというと、レビューで指摘されるようにしてあるから、そうならざるをえない状況になっている。
あと、カバレッジ見て、マージできないようにしているから、簡単に単位がおかしい状態で開発ブランチにマージされることはない。
どっちかというと、SVNとかで起きやすい気が。。。
