概要
プルリクエストとは、リポジトリへの変更を提案し、その変更についてレビューなどの共同作業を行うための仕組みです。変更はブランチを介して提案されます。適用する内容を含むheadブランチから、変更の適用先であるbaseブランチに向けてプルリクエストを作成し、承認された内容だけが取り込まれます。コミットメッセージ
コミットメッセージは、コミットに含まれる変更内容を要約する説明です。書き方をチームの規約として統一すると、履歴のどのコミットが何を変更したのかを一定の形式で追跡できます。 規約にはConventional Commitsの形式が広く使われます。<型>: <要約>の形式で、先頭に変更の種類を示すプレフィックスを付けます。
Conventional Commitsと合わせて、Semantic Versioningを使うことがあります。
MAJOR.MINOR.PATCHの形式で、変更の互換性に応じて上げるバージョンレベルを決めます。ライブラリやAPIなど、互換性を管理する必要がある開発で利用することがあります。この2つを組み合わせると、コミットメッセージから変更内容を理解しやすくなり、リリースのバージョン番号を機械的に決定できるようになります。
組み合わせる場合は、
<レベル>-<型>: <要約>のように型の前にバージョンレベルを付けます。破壊的変更を伴う機能追加はmajor-feat、互換性に影響しない小さな機能追加はpatch-featのように、型だけでは決まらないバージョンレベルを明示できます。
コミットメッセージは<型>: <要約>の1行だけでも成立します。変更の背景や理由を説明したい場合は、空行を挟んで本文やフッターを加えます。
タイトル
プルリクエストのタイトルは、変更内容を1行で要約する説明です。タイトルは一覧・通知・マージ後の履歴に表示されるため、本文を開かなくても変更内容を判別できる書き方に統一します。 タイトルはコミットメッセージをベースに、同じくConventional CommitsとSemantic Versioningの形式で決めます。コミットが1つのプルリクエストではそのコミットメッセージをそのまま使い、複数のコミットを含むプルリクエストでは変更全体を代表する型と要約を選びます。テンプレート
プルリクエストの作成時に説明欄に自動挿入されるMarkdownのテンプレートを用意することができます。テンプレートがあると、概要・変更点・動作確認といった説明の構成がプルリクエストごとにばらつかず、レビュアーに渡すべき情報を事前にルール化できます。1
テンプレートファイルを作成する
リポジトリに
.github/PULL_REQUEST_TEMPLATE.mdを作成します。2
雛形を書く
レビュアーが必要とする情報を、見出しとコメントで区切って並べます。
3
デフォルトブランチへマージする
テンプレートはデフォルトブランチに存在して初めて適用されます。マージ後に作成されるプルリクエストから、説明欄に雛形が自動で挿入されます。
Draft
Draftとは、レビューの準備が整っていないことを明示するプルリクエストの下書き状態です。Draft状態の間はマージがブロックされるため、作業途中の変更が誤って取り込まれることはありません。 未完成の段階でDraftとしてプルリクエストを開いておくと、実装や設計の方向性について、実コードの差分を見ながら早い段階でフィードバックを得られます。文書や口頭のすり合わせと違い、動くコードを前提に議論できるため、レビュアーと認識を早い段階で合わせられます。 必要なフィードバックが揃い、認識が合ったら、そのまま作業を継続しても、Draftのプルリクエストをcloseして新たにプルリクエストを作り直しても構いません。作業が進むほど方向転換のコストは膨らむため、早い段階で手戻りしてサンクコストを最小限に抑える手段としてDraftは有効です。 作成時に「Create draft pull request」を選択し、レビューを依頼できる状態になったら「Ready for review」でDraft状態を解除します。粒度
プルリクエストの粒度とは、1つのプルリクエストが1つのことに注力できているかという、変更内容の一意性です。差分の行数やファイル数ではなく、変更内容が一意であるかどうかで測ります。サイズと粒度の違い
サイズ（変更行数・ファイル数）と粒度（変更内容の一意性）は別の尺度であり、分割の判断に使うのは粒度です。判断基準は、差分が大きいかどうかではなく、プルリクエストの変更内容が一意である（1つのことに注力できている）かどうかです。なぜ粒度が重要か
焦点の絞られた差分は、レビューする範囲も絞られます。作業量の合計が同じでも、10の変更を1つのプルリクエストでレビューするより、1の変更を10個のプルリクエストに分けてレビューする方が、作成者・レビュアー双方の負担が小さくなります。レビューが速い
変更内容が一意な差分はレビュアーの頭に収まるため、レビューが後回しにされず、数分で終わります。
切り戻しが容易
変更内容が一意なプルリクエストをrevertすれば、その変更だけを巻き戻し、余計なものを巻き込みません。
conflictが減る
生存期間が短いブランチは、conflictが発生しにくくなります。
原因特定が速い
変更内容が一意なプルリクエストは影響範囲も絞られるため、障害時の切り分けが速くなります。