pull request のベスト プラクティス

pull request の作成のベスト プラクティス

pull request を作成するときは、いくつかのベスト プラクティスに従って、よりスムーズなレビュー プロセスを実現します。 pull request の作成の詳細については、「pull request の作成」を参照してください。

小さい PR を書き込む

1 つの目的を満たす、焦点を絞った小さな pull request を作成することを目的とします。 pull request を小さくすると、レビューとマージが簡単かつ迅速になり、バグを導入する余地が少なくなり、変更の履歴がより明確になります。

最初に独自の pull request を確認する

送信する前に、独自の pull request を確認、ビルド、テストします。 これにより、他のユーザーがレビューを開始する前に、見逃した可能性のあるエラーや入力ミスをキャッチできます。

コンテキストとガイダンスを提供する

pull request の内容をレビュー担当者がすぐに理解できるように、pull request の明確なタイトルと説明を記述します。 pull request の本文は次のようになります。

• pull request の目的
• 変更点の概要
• 問題の追跡や以前の会話など、追加のコンテキストへのリンク

レビュー担当者を支援するには、必要なフィードバックの種類を共有します。 たとえば、クイック ルックやより深い批判が必要ですか?

pull request が複数のファイルに対する変更で構成されている場合は、ファイルをレビューする順序に関するガイダンスをレビュー担当者に提供します。 開始する場所とレビューを続行する方法を勧めます。

pull request の管理のベスト プラクティス

リポジトリ メンテナである場合は、次の手順を実行して、共同作成者がリポジトリに作成する pull request を管理および標準化します。

pull request テンプレートを使用する

pull request テンプレートを使用すると、他のユーザーがリポジトリに pull request を作成するときに含める情報をカスタマイズおよび標準化できます。 リポジトリにプルリクエストのテンプレートを追加すると、プロジェクトのコントリビューターはプルリクエストの本体にテンプレートの内容を自動的に見ることになります。 詳しくは、「リポジトリ用のプルリクエストテンプレートの作成」を参照してください。

pull request テンプレートを使用して、リポジトリのレビュー プロセスを標準化できます。 たとえば、テンプレートにタスク一覧を追加することで、作成者が pull request をマージする前に完了させるタスクの一覧を含めることができます。 詳しくは、「タスクリストについて」をご覧ください。

pull request をマージすると issue を自動的に閉じることができるように、共同作成者に pull request 本文に issue の参照を含めるように要求できます。 詳しくは、「Pull RequestをIssueにリンクする」を参照してください。

コード所有者を定義する

特定の個人がリポジトリ内の特定のコードまたはファイルに対する変更を常にレビューすることを確認する場合があります。 たとえば、チームのテクニカル ライターが docs ディレクトリの変更を常にレビューする必要がある場合があります。

コード所有者となるリポジトリ中のコードに対して責任を負うと考えられる個人あるいはチームを指定できます。 コード所有者は、他者が所有するファイルを変更するプルリクエストをオープンすると、自動的にレビューをリクエストされます。 特定の種類のファイルまたはディレクトリ、およびリポジトリ内の異なるブランチに対してコード所有者を定義できます。 詳しくは、「コードオーナーについて」を参照してください。

保護されたブランチを使用する

保護されたブランチを使用すると、特定の条件が満たされるまで、pull request が main などの重要なブランチにマージされるのを防ぐことができます。 たとえば、CI テストや承認レビューに合格することを要求できます。 詳しくは、「保護されたブランチについて」を参照してください。

プッシュ ルールセットを使用する

プッシュ ルールセットを使用すると、ファイル拡張子、ファイル パスの長さ、ファイルとフォルダーのパス、ファイル サイズに基づいて、プライベート リポジトリまたは内部リポジトリとそのリポジトリのフォーク ネットワーク全体へのプッシュをブロックできます。

プッシュルールはリポジトリへのすべてのプッシュに適用されるため、ブランチのターゲット設定は必要ありません。

プッシュ ルールセットを使用すると、次のことができるようになります。

• ファイル パスを制限する: 指定したファイル パスに変更を含むコミットがプッシュされないようにします。

  これには fnmatch の構文を使用できます。 たとえば、test/demo/**/* を対象とする制限により、test/demo/ ディレクトリ内のファイルまたはフォルダーへのプッシュが禁止されます。 test/docs/pushrules.md を対象とした制限により、test/docs/ ディレクトリ内の pushrules.md ファイルへのプッシュが禁止されます。 詳しくは、「リポジトリのルールセットの作成」を参照してください。

• ファイル パスの長さを制限する: 指定した文字制限を超えるファイル パスを含むコミットがプッシュされないようにします。

• ファイル拡張子を制限する: 指定したファイル拡張子を持つファイルを含むコミットがプッシュされないようにします。

• ファイル サイズを制限する: 指定したファイル サイズの制限を超えるコミットがプッシュされないようにします。

フォークされたリポジトリのプッシュ ルールセットについて

プッシュ ルールは、リポジトリのフォーク ネットワーク全体に適用され、リポジトリへのすべてのエントリ ポイントが確実に保護されます。 たとえば、プッシュルールセットが有効になっているリポジトリをフォークした場合、フォークされたリポジトリにも同じプッシュルールセットが適用されます。

フォークされたリポジトリの場合、プッシュ ルールのバイパス アクセス許可を持つユーザーは、ルート リポジトリのバイパス アクセス許可を持つユーザーだけです。

詳しくは、「ルールセットについて」を参照してください。

自動化されたツールを使用してコードのスタイルをレビューする

リポジトリの pull request でリンターなどの自動化されたツールを使用して、一貫性のあるスタイルを維持し、コードをより理解しやすくします。 自動化されたツールを使用して、入力ミスやスタイルなどの小さな問題をキャッチすると、レビュー担当者が pull request の内容に集中するための時間を多く取れるようになります。

たとえば、GitHub Actions を使用して、継続的インテグレーション (CI) ワークフローの一部として pull request で実行できるコード リンターを設定できます。 詳しくは、「継続的インテグレーションについて」を参照してください。