開発現場で、「自分のプルリクエストだけなかなかクローズされないぞ…」と思った経験ありませんか？
プルリクエストについてフィードバックをいただき、書籍やブログを読み、プルリクエストの本質や運用方法について考える中で、その改善策を模索してきました。
この記事はそんな私と同じ悩みを抱える方へ向けた記事となっております。
内容自体は理解できても実際に実現するのが難しい側面もあります。
それでも、プルリクエストを通じてプロセスを改善し、より良い開発環境を追求するための一助となれば幸いです！
🧑💻 対象読者
- プルリクエストを書く経験が浅い方
- プルリクエストがなかなかクローズされずに悩んでいる方
- チーム全体のプロセス改善や効率的なレビュー運用を実現し、後輩育成にも役立てたい方
放置されたプルリクエストが引き起こす負担
プルリクエストが長期間オープンのままだと、いつも「やらなきゃ」と頭の片隅に残ってしまい、知らず知らずのうちに認知的な負担がかかってしまいます。
その結果、集中力が分散し、次々とタスクを切り替える必要が出てくるため、作業の効率が落ちてしまうことも...
片付け上手なプルリクエストが導く―集中と効率の高い仕事のリズム
プルリクエストが停滞せず、ばしばしクローズされることより、開発サイクルが短くなることで、プロダクト改善への取り組みがスムーズに進みます。
また、プルリクエストがすぐに片付くと、エンジニアは未処理のタスクに悩まされることなく、目の前の仕事に集中できるようになります。仕事がスムーズに進むことで、達成感を感じやすくなり、次のタスクにも意欲的に取り組める環境が整うのもポイントです。
このように、迅速なプルリクエストのクローズは、プロダクトの価値向上とエンジニアの開発者体験の向上を実現する大切なポイントとなっています。
プルリクエスト作成前の準備（要件の整理）
実装に取り掛かる前に、まず「何を実現するのか」という要件をしっかり整理することが不可欠です。要件が曖昧なまま実装に取りかかると、実装の方向性がぶれて出戻りになったり、追加実装が発生原因となります。
そこで、事前に用件を明確にし、チーム全体で共通の認識を持つことが、効率的な開発プロセスの基盤となります。
当たり前と思いますが、結構大事です！
弊社の取り組み
弊社は大規模スクラム開発（LeSS）を採用しており、機能実装に先立ってリファイメントやスプリントプランニングを実施しています。独自にカスタマイズしている部分もあります。
リファイメント 1
リファイメント 1 では代表、フロントエンド、バックエンド、デザイナー各部門のトップが集まり、プロダクトバックログアイテム（以下 PBI）について大まかな議論を行い、サービス全体の方向性や懸念事項を共有します。
リファイメント 2
フロントエンドとバックエンドのエンジニアメンバーが集まり、先の議論をもとに具体的な実装方針、API 設計、依存関係などを詳細に検討します。
その後、フロントエンドメンバーやバックエンドメンバーで別れてさらに詳細なリファイメントを行い、見積もりを出します。
PBI のリファイメントフェーズはここで一旦終了です。
スプリントプランニング
スプリントで着手する PBI については、スプリントプランニングを行います。
スプリントプランニングはリファイメントで話した内容を元に設計方針や優先順位、タスク分解、リファクタリング項目の洗い出し、どのタスクをモブプロで行うかなど、話し合っていきます。
作業に取り掛かる前までにステップを踏んで議論されているため、エンジニア同士である程度同じ方向を向いているものの、実装がブレることがまだまだ多いです。
ぶれそうな実装や難易度の高い実装ははペアプロやモブプロで行います。
参考資料
モブプログラミング・ベストプラクティス ソフトウェアの品質と生産性をチームで高める
いよいよ本題です。前置きが長くてすみません 🙏
お作法その１：プルリクエストを小さい粒度に分ける
プルリクエストをスムーズにレビューしてもらうためには、変更を一度に大量に盛り込むのではなく、機能単位に分割したプルリクエストを作成することが重要です。こうすることで、レビュアーはプルリクエストごとに「何を変更しているのか」を明確に理解でき、全体としてのレビュー効率が向上します。大きな粒度になる場合は適宜フィーチャーブランチを切り、その中でさらにブランチを切ってプルリクエストを作成します。
適切な粒度のプルリクエストを作るための観点
-
E2E で完結すること
プルリクエストは本番環境に出しても問題ない状態（テストが通り、動作上も問題なし）を目指します。これにより、各機能が独立して動作することが保証され、レビュアーが安心してチェックし、リリースできる状態となります。 -
機能ごとに分割する
ひとつのブランチは、ひとつの機能にフォーカスすることで、変更の意図が明確になり、理解しやすくなります。できれば一言で説明できるような粒度にできるのが望ましいです。 -
依存関係の最小化する
フロントエンドとバックエンドが並行して開発される場合、互いの依存関係を極力排除します。依存がある場合は、関連機能を別途切り出し、ステージングブランチなどで動作確認や統合テストを行います。
いきなり難しいですね。書いてみたものの、いい感じにプルリクエストを作るのには、熟練の技術と経験が必要そうです！
お作法その２：コミットを整理する
コミットは、コード変更の「物語」を伝える手段と考えます。プルリクエストの詳細で全体の背景や設計意図を把握した上で、レビュアーは各コミットを順にたどり、どのような流れで最終実装に至ったのかを理解します。ここでは、効果的なコミット管理を実現するための具体的なポイントについて解説します！
機能変更コミットと機械的コミットの区別
-
機能変更コミット
バグ修正、機能追加、リファクタリングなど、コードのロジックや動作に直接影響する変更を含みます。
これらは、変更の意図や背景を明確に記述することで、レビュアーが「何を、なぜ」変更したのかをすぐに把握できるようになります。 -
機械的コミット
コードのフォーマッティング調整、タイポ修正、ボイラーテンプレートの追加・削除など、機能自体の動作には直接関与しない変更を指します。
これらは、場合によっては個別に記録されることで、どの処理が行われたかを明確に示すメリットもありますが、変更が細かく分散しすぎると本質的な変更内容が埋もれてしまう可能性があります。
そのため、状況に応じてスカッシュなどで統合し、全体の履歴をシンプルに保つ工夫が望まれます。
参考資料
論理的にコミット順序の整理する
「最初から全てを知っていた状態で最短距離で実装した」 かのように最低限のコミットを積んでいくことがコミットを整理する際の重要なポイントになります。
- コミットの順序は、実装の進行状況を示すタイムラインとして機能します。
- 論理的に順序を整理することで、レビュアーは各コミットを順番に追いながら、どのような経緯で最終的な実装に至ったのかを直感的に理解できます。
- 整理された履歴は、変更の流れを明確に伝え、コードレビューをスムーズに進めるための基盤となります。
参考資料
コミットメッセージを丁寧に書く
- 各コミットメッセージには、何を、なぜ変更したのかを具体的に記述し、レビュアーがその意図をすぐに把握できるようにします。
- 必要に応じて、ディスクリプションも利用する。注意すべき点や参考情報も明記し、変更の背景が理解しやすいコミットメッセージを作ります。
- コミットメッセージは１行で、ディスクリプションは利用せず、代わりにプルリクエストのコメントを活用するという運用もありだと思います。
参考資料
お作法その 3：レビュワーに優しいプルリクエストの作成
わかりやすいプルリクエストは、レビュアーが迅速に変更の意図を把握し、後から実装の経緯をたどる際にも大いに役立ちます。丁寧なプルリクエスト説明文と、明確で具体的なタイトルが揃っていると、変更点や設計意図が理解しやすくレビュー作業が格段に効率化されます。
ここではレビュワーに優しいプルリクエスト作成が実現するポイントを以下の観点で解説します！
- タイトル作成のポイント
- 説明文（ディスクリプション）のポイント
- コメントのポイント
タイトル作成のポイント
具体的で明確なプルリクエストのタイトルを心がけましょう。良いプルリクエストのタイトルは見るだけで変更内容や目的を瞬時に理解できます。レビュワーの頭の中にプルリクエストで対応した内容がすんなり入るので、その後のレビューがしやすくなります。
具体的で明確なプルリクエストのタイトルを心がけましょう。
この文章がすでに具体的で明確ではないため、実際に私がダメ出しを食らった例を出します。
背景がわからないと説明しにくいので、少し長いですがお付き合いください 🙏🏻
具体例
実装を変更する背景
- 対象は、バナーを扱うコンポーネント（
hogehogeComponent）です。バナーを扱うコンポーネントは複数あります。 - このコンポーネントでは、バナーサイズとして「大」と「小」の 2 種類が選べるようになっています。
- バナーが登録されていない場合、「背景画像が未登録です」と表示される画像が用意されています。
- ただし、バナーサイズが「大」の場合と「小」の場合では、表示すべき画像のアスペクト比が異なります。具体的には、サイズ「大」では縦長の画像が、サイズ「小」では横長の画像が表示される必要があります。
そして、私がプルリクエストのタイトルに書いていたのがこれです
「画像なしを小に対応する」 🙈（ひどい）
これに対していただいたフィードバックは以下の通り
- どのコンポーネントに対するプルリクエストなのか、タイトルからスコープが明確でない。
- 「画像なしを」という表現が、バナー画像に対するものなのか、コンポーネント全体の仕様変更なのか分かりにくい。
- 「小に対応する」とは具体的にどのような変更か、例えば小さいサイズ用の画像への切り替えや、レイアウトの変更がどう行われるかが不明確。
ちなみに改善した結果こうなりました。
hogehogeComponenでバナーサイズ「小」の場合に適した「背景画像が未登録です」画像を表示する
相手（レビュワー）の立場で考える難しさを痛感しています。
自分の子供に「人の気持ちになって考えよう」などと偉そうに言ってますが、全然できていないことを反省します。
プルリクエスト説明文作成のポイント
レビュアーがプルリクエストの背景や目的、変更内容を迅速に理解できるようにするため、プルリクエスト説明文は具体的かつ整理された情報を提供することが重要です。以下のポイントを意識して説明文を作成しましょう。
背景と目的の明確化(Why)
- このプルリクエストで何を達成しようとしているのか、どの問題を解決するための変更なのかを簡潔に記述します。
- 関連する PBI や issue、または議論した Slack スレッドや Notion ページを添付することで、背景情報が一目で分かるようにします。
- Figma や XD で作成したデザイン画像やリンク、バグの動画などの視覚資料も効果的です。
変更内容の整理(How)
- どの部分がどのように変更されたのか、具体的な変更箇所やその意図を整理して記述します。
- 事前に議論された内容や参考にした実装のプルリクエストを含めることで、レビュアーがプルリクエスト内で再度詳細な議論をする必要がなくなります。
やっていないことの明示
- このプルリクエストであえて実施していない変更や、今後の課題として残している部分を記載します。
- これにより、レビュアーは「今回の対象はここまで」と把握でき、不要な疑問や指摘を防ぐことができます。
確認事項の提示
- レビュアーに特にチェックしてほしいポイントを明示します。
- 具体的なチェックポイントが明記されていると議論がしやすいです。
参考資料
プルリクエストでのコメントのポイント
プルリクエストにコメントを残す際、特に「Why」の部分に着目して記述することが大切です。コード自体に変更の理由をコメントとして残すのが望ましいですが、コードに直接残すのが難しい場合やコードに残すほどでもない場合はプルリクエストにコメントを残しておくとわかりやすいです。
その他の Tips
ドラフトプルリクエストからオープンした後に気をつけること
ドラフト状態からオープン状態にプルリクエストを変更した後は、フォースプッシュを避けることが重要です。フォースプッシュを行うと、コミットハッシュが更新されて、どのコミットに対してコメントが付いているのか分かりにくくなります。既に approve されたプルリクエストの場合、レビューワーがどこまでをみて approve したのかわからなくなるため、再度確認をしてもらうことになります。
プルリクエスト作成過程の整理
ブランチを切ったら、まずは変更のない状態でプッシュして Draft のプルリクエストを作成することをお勧めします。Draft のプルリクエストを作成したら、プルリクエストのタイトルと説明文を書きます。この時点で実装者自身でも頭が整理できます。
Draft のプルリクエストができたら実装に入ります。実装を進めながらプルリクエストの説明文を整えていくイメージです。
このプロセスにより、実装者自身でも経緯を整理しながらレビュアーに伝わりやすい文章を書くことができます。
終わりに
拙い文章でしたが、ご拝読ありがとうございます！
自分自身に対するフィードバックや運用方法について考える中で培ってきた情報を整理しました。この内容が理解できれば、明日からいいプルリクエストが作れそうですね！
...とはなりません 🫥
プルリクエストを作るにも技術や経験が必要なので、一朝一夕に作ることはできないのです。
「いい感じにプルリクエストを作って〜」と言われても内容を分解すると
-
要件を理解する
→ 当たり前なようで実は難しい。ドキュメントが揃っていなかったり、ドメイン知識にがないと理解できないところも多くなる -
実装箇所を明確にする
→ プロダクトコード全体の知識やドメイン知識、エンジニアとしてのスキルが求められる -
タスクを分解する
→ E2E で分解できるタスクを見分けるのは熟練の技が必要 -
理解しやすい粒度で機能ごとのブランチを作成する
→ FE や BE との依存関係や優先順位など、気を回す点が多くて難しい -
レビュワーがわかりやすいタイトルやディスクリプションを整理する
→ ニホンゴムズカシイ -
レビュワーが理解しやすいようにコミットを整理する
→ Git のコマンドをしっかり理解していないと手こずる
など、難易度の高いタスクを一つ一つこなしていき、綺麗に整理する技能が求められます。
完璧なプルリクエストなんて一朝一夕には作れませんが、共に学び、成長していければと思います。
一緒に頑張っていきましょう！
それでは 👋
Discussion