Pull Request

プルリクエストとは何か？

プルリクエスト（Pull Request、略称PR）は、GitHub上でコードの修正や新規機能作成をレビューするための重要な機能です。
GitHubを使用する多くのプロジェクトでは、コードの修正・新規機能作成をした後、他の開発者やプロジェクト管理者に内容を確認してもらうためにプルリクエストが使われています。
プルリクエストを介して、コードの修正・追加を他の人に確認・指摘してもらい、最終的にコードをプロジェクトにマージします。

なぜプルリクエストが必要なのか？

他の開発者にソースコードをレビューしてもらうことで、未然にバグを解消したり誤った記述を修正できるため、品質が保証されたソースコードをリリースすることが可能になります。

プルリクエストには、コードレビューを簡潔にするための以下の機能があります。

プルリクエストの機能

• 変更箇所の比較表示
  GitHubでプルリクエストを送るとリポジトリ変更前と変更後の差分比較が簡単に行えます。 この機能によりどこに変更を加えたのか、適切な変更なのかを他の開発者が判断しやすくなります。

• コメント機能
  プルリクエストが送られたソースコードにはコメント機能を使って他の開発者からのレビュー内容を記述することも可能です。 変更内容に問題がある場合や、より良い変更方法をチーム内で共有し改善することが出来ます。

• 他の開発者への変更通知
  プルリクエストを任意の開発者を指定して送ることで、指定した開発者がリポジトリに変更があったことを通知として受け取ることが出来ます。

プルリクエストの作成手順

プルリクエスト作成手順からマージされるまでの一連の流れを説明します。

1. プルリクエストの作成

ローカルからGitHubへプッシュしてしばらくの間は画像の赤枠のように「Compare & pull request」のボタンが表示されるのでこちらをクリックしてプルリクエストの作成を進めていきましょう。

ヒント

時間が経って表示されなくなってしまった場合、「Pull requets」タブの「New pull request」ボタンからプルリクエストを作成することが可能です。

2. プルリクエストのブランチの設定・タイトル・内容入力

プルリクエストを作成すると、マージ先のブランチを設定します。

左側の「base: main」と表示されている方がマージ先のブランチで、右側の「compare: feature/1」と表示されている方がコードを修正したマージしたいブランチです。

下の赤枠にはプルリクエストのコメントと内容を記述します。

入力が完了したら「Create pull request」ボタンをクリックしてプルリクエストの作成完了です。

ヒント

Work in Progress(WiP)

1. Work in Progress(WiP)とは

Work in Progress(WiP)とは新規作成・修正がまだ完了していないことを示すためにWiPマークを使用できます。
これは、他の開発者に対して「これはまだ最終版ではない」という警告の意味を持ちます。 またWiP状態だと、プルリクエストをマージすることは出来ません。

WiPのマークは、プルリクエストがどの段階にあるかを示し、プロジェクトの進行状況を追跡するのに役立ちます。
開発者はコードの一部を共有し、他のチームメンバーやコミュニティのフィードバックを受けながら、作業を進めることができます。

2. Work in Progress(WiP)の設定

プルリクエストの作成時に、WiPの設定を行うことが出来ます。

「Create draft pull request」を選択することで、プルリクエストをWiP状態にすることが出来ます。

プルリクエストの作成後に、WiPの設定を行うことも出来ます。

「Convert to draft」を選択することで、プルリクエストをWiP状態にすることが出来ます。

2. Work in Progress(WiP)の解除

新規作成・修正が完了した場合は「Ready for review」を選択することで、プルリクエストをWiP状態から解除することが出来ます。

3. プルリクエストの確認

プルリクエストが作成出来たら「Pull requests」のタブ右側に数値が表示されるようになりますので作成したプルリクエストを確認します。
GitHub上ではコミットの詳細、変更内容の確認を行える機能があります。

コミット履歴の確認

コミット履歴の確認を実施する場合、「Commits」のタブを開くことでコミット単位でコミットの内容を確認出来ます。

コミット一覧

コミット詳細

GitHub Actionsの確認

GitHub Actionsの確認を実施する場合、「Checks」のタブを開くことでGitHub Actionsの実行結果を確認出来ます。
GitHub Actions は、ビルド、テスト、デプロイのパイプラインを自動化できるプラットフォームです。
リポジトリに対するすべての pull request をビルドしてテストしたり、マージされた pull request を運用環境にデプロイしたりするワークフローを作成することができます。

例えばpull requestが作成された時に、自動でPHPstanやPHP_CodeSnifferなどの静的解析ツールを実行してコードのチェックすることが出来ます。

ヒント

GitHub Actionsについては詳しくは下記を参照してください。
https://docs.github.com/ja/rest/guides/using-the-rest-api-to-interact-with-checks?apiVersion=2022-11-28

GitHub Actionsの実行結果

「Checks」のタブ内でも、GitHub Actionsを確認出来ますが「Conversation」内でも確認できます。

ファイル全体の変更差分の確認

ファイル全体の変更差分の確認を実施する場合、「File change」のタブを開くことで全ファイルの修正内容を確認出来ます。

4. プルリクエスト作成後の各種設定

プルリクエストの内容を確認出来たら、レビュー依頼者やlabelの設定、issueの紐づけを行います。

1. Labelの追加

プルリクエストに対して、Labelを紐づけることが出来ます。
labelを紐づけることによって、プルリクエストのステータスや内容を確認することが出来ます。

画面右側の「Labels」の歯車をクリックし、対象のLabelを選択します。

選択後、Labelsに選択したLabelが追加されます。

2. issueの紐づけ

プルリクエストに対して、issueを紐づけることが出来ます。
issueを紐づけることによって、プルリクエストの関連性や修正内容の確認がしやすくなります。

画面右側の「Development」の歯車をクリックし、対象のissueを選択します。

選択後、Developmentに選択したissueが追加されます。

3. レビューの依頼

修正した内容を確認してもらうために、レビューを依頼することが出来ます。
基本的にレビュアーを選択すると通知が飛ぶことがあるためソースの確認、その他の設定が完了してからレビュー依頼を行うようにしましょう。

画面右側の「Reviewers」の歯車をクリックし、対象の開発者を選択します。

選択後、Reviewersに選択した開発者が追加されます。

プルリクエストを出す前の注意点

プルリクエストを出すにあたり基本的には下記項目に注意する必要があります。

• スペルミスがないか
• 不要なコードや意味のないコメントアウトが残っていないか
• コメントがコードと食い違っていないか
• コピペした箇所を見直したか
• インデントがズレていないか
• 処理内容や変数用途と名前が一致しているか
• 型が大き過ぎないか、関数が長すぎないか
• 一行が（横に）長すぎないか
• IDEに警告が発生していないか
• 横展開調査したか
• 既存の共通処理があることを見逃していないか

基本的には上記内容の観点で確認していく必要があるがプロジェクトや所属によっては独自ルールなどもあるので別途確認が必要になります。

例えばシステム開発事業部1課ではプルリクエストを出す前に下記のチェックリストを確認することをルールとしています。

## [必須] 対応内容

- このプルリクで何をしたのか？
- 追加機能・修正内容など具体的に

## [必須] 前提タスク・マイグレーション等の有無

* __前提タスク（先に追加されていなければならない機能が存在するか）__
    * [ ] __あり__　Issueリンクを付けること
    * [ ] なし
* __マイグレーションの追加__
    * [ ] __あり__　ファイルパス記載
    * [ ] なし
* __ライブラリの追加__
    * [ ] __あり__　ライブラリ名・用途
    * [ ] なし

## [必須] 影響調査

- どんなことを調査・確認したのかを記載

## [必須] 確認観点の共有
<!-- 管理者についてはこの項目は任意とします -->
- レビュワーへの参考情報（実装上の懸念点や注意点、特によく見て欲しい所などあれば記載）
- コピペして動いてはいるが、内容が理解できていないなどもここに記載
- 動作確認を行う上で必要な作業の情報

## [必須] セルフチェックリスト
<!-- 管理者についてはこの項目は任意とします -->
- マージリクエスト
    * [ ] マージするブランチは誤っていないか
    * [ ] Issueと紐づけられているか
    * [ ] タイトルは適切か
- コミット内容
    * [ ] インデントがズレていないか・一行80文字以下(psr-12準拠)もしくはPJで決められた文字数以内か
    * [ ] 不要なコミットがないか（コメントアウト・動作確認用出力など）
    * [ ] コメントがコードと食い違っていないか・関数名と処理、変数名と用途は一致しているか
    * [ ] 型が大き過ぎないか、関数が長すぎないか
    * [ ] 既存の共通処理があることを見逃していないか
    * [ ] ループ処理内でDBアクセスをしていないか・DBアクセスを極力避けられているか
<!--
プロジェクトルールがあるならlinter等を用いてコードチェックを行わせること！
 -->

## [任意] 申し送り事項

- このIssueで対応せずに別Issueとして切り出したものがある
- 新しいライブラリ・マイグレーションファイルを追加したので、マージ時にアナウンスして欲しい等

## [必須] 単体テスト

- タスクリストに従い実施し、表示確認するものはエビデンスを貼付

5. プルリクエスト作成後対応

コメントの追加

レビュアーは変更箇所に対して修正依頼などがあれば「+」ボタンからコメントをすることが出来ます。

コメントを入力した後は、Review changesのCommentを選択して「Submit review」ボタンをクリックしてコメントを送信します。

コメントの返信

プルリクエストを作成した後は、レビュアーから修正依頼やコメントがある場合があります。
GitHubではコメントに対しても返信をすることが出来ます。
多くは修正内容に対しての質問や指摘を行うために使用されますのでコメントがあれば返信するようにしましょう。

手順はコメントの追加と同じです。
コメントを入力後、Review changesのCommentを選択して「Submit review」ボタンをクリックしてコメントを送信します。

コメント返信後、レビュアーが返信コメントや修正内容を確認して「Resolve conversation」にチェックを入れてコメントを閉じます。
基本的にコメントが閉じるまではプルリクエストを確認するようにしましょう。

6. プルリクエストのマージ

レビュアーはプルリクエストの変更内容に問題がなければ「Merge pull request」ボタンをクリックすることで変更内容をマージ先のブランチに反映させることが出来ます。

マージが完了したら「Pull request successfully merged and closed」に変更され、マージ元となったブランチを削除することが出来ます。

ヒント

ブランチの削除はプロジェクトによっては禁止されている場合がありますので要確認