テンプレートを使用して pull request の説明を改善する
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
適切な pull request の説明を記述することは、レビュー担当者がコードをレビューするときに期待する内容を把握するのに役立つ優れた方法です。 また、テスト、単体テストの追加、ドキュメントの更新など、すべての変更に対して行う必要のある作業を追跡するのに役立つ優れた方法でもあります。 pull request テンプレートは、開発者が組織の標準を満たす優れた pull request の説明を作成する際に役立てることができます。
この記事では、pull request テンプレートの使用を開始する方法について説明します。
注意
pull request テンプレートにはガイダンスがありますが、アドバイザリしか含まれていません。 ブランチ ポリシーを使用して、メインなどのキー ブランチに pull request を要求する、ビルドの成功を要求する、必要なレビュー担当者を強制するなどのベスト プラクティスを実施します。 詳細については、ブランチ ポリシーに関するページを参照してください。
pull request テンプレートとは
pull request テンプレートとは、pull request の作成時に pull request の説明に追加される Markdown テキストを含むファイルです。
Thank you for your contribution to the Fabrikam Fiber repo.
Before submitting this PR, please make sure:
- [ ] Your code builds clean without any errors or warnings
- [ ] You are using approved terminology
- [ ] You have added unit tests
Azure Repos では、次の種類の 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_template.md または pull_request_template.txt という名前のファイルを作成し、次のいずれかのフォルダーにあるリポジトリの既定のブランチに保存します。
- リポジトリのルート フォルダーに格納されている
.azuredevopsという名前のフォルダー - リポジトリのルート フォルダーに格納されている
.vstsという名前のフォルダー - リポジトリのルート フォルダーに格納されている
docsという名前のフォルダー - リポジトリのルート フォルダー
pull request テンプレートを格納する場所に柔軟性を与えるために、複数の保存先が用意されています。 pull request が作成されると、Azure Repos が決まった順序で指定されたフォルダーを検索し、見つけた最初の既定の pull request テンプレートを使用します。
リポジトリに新しい pull request が作成されると、ブランチ固有の pull request テンプレート が適用されない限り、既定の pull request テンプレートのコンテンツを使用して、pull request の "説明" フィールドに事前入力されます。
[テンプレートの追加] ドロップダウンから選択することで、必要に応じて、この説明を編集または追加したり、追加の pull request テンプレートを付け加えたりできます。
注意
既定またはブランチ固有の pull request テンプレートが自動的に適用されると、通常は既定の説明に使用される標準のコミット メッセージが置き換えられます。 [コミット メッセージを追加します] を選択して、再度追加できます。
ブランチ固有の pull request テンプレート
ブランチ固有の pull request テンプレートは、特定のブランチを対象とする pull request 向けに構成されます。 ブランチ固有の pull request テンプレートを使用してリポジトリを構成するには、ブランチに基づいて .txt または .md ファイルを作成します。 名前は、ブランチ名の最初のレベル (main、dev、release、feature など) と一致している必要があります。 各ブランチ固有の pull request テンプレートは、pull request がそのブランチまたはその下に含まれるブランチを対象とする際に適用されます。 たとえば、feature.md という名前の pull request テンプレートは、pull request が feature ブランチまたは feature/* ブランチを対象とする場合に適用されます。
ブランチ固有の pull request テンプレートは、フォルダー階層 pull_request_template/branches/ を使用してリポジトリの既定のブランチに保存する必要があります。 これらのフォルダーは、リポジトリ内の次のいずれかのフォルダーに基づいている必要があります。
- リポジトリのルート フォルダーに格納されている
.azuredevopsという名前のフォルダー - リポジトリのルート フォルダーに格納されている
.vstsという名前のフォルダー - リポジトリのルート フォルダーに格納されている
docsという名前のフォルダー - リポジトリのルート フォルダー
たとえば、dev ブランチへのすべての pull request に適用する必要があるブランチ固有の pull request テンプレートは、dev.md または dev.txt という名前になり、次のいずれかの場所に配置されます。
<repository root>/.azuredevops/pull_request_template/branches/<repository root>/.vsts/pull_request_template/branches/<repository root>/docs/pull_request_template/branches/<repository root>/pull_request_template/branches/
既定の pull request テンプレートと同様に、ブランチ固有の pull request テンプレートを格納する場所に柔軟性を与えるために、複数の保存先が用意されています。 pull request が作成されると、Azure Repos は、指定されたフォルダーをブランチ固有の pull request テンプレートに対して決められた順序で検索し、見つけたブランチ名と一致する最初のフォルダーを使用します。 ブランチ固有の pull request テンプレートが見つからない場合は、前述の「既定の pull request テンプレート」セクションで説明したように、Azure Repos は既定の pull request テンプレート検索します。
追加の pull request テンプレート
既定およびブランチ固有の pull request テンプレートに加えて、追加の pull request テンプレートを構成できます。 これらは、.md または .txt のファイルであり、既定のブランチ内の次のいずれかのフォルダーに配置されています。
<repository root>/.azuredevops/pull_request_template/<repository root>/.vsts/pull_request_template/<repository root>/docs/pull_request_template/<repository root>/pull_request_template/
pull request が作成されたら、[テンプレートの追加] ドロップダウンから選択することで、使用可能な pull request テンプレートを追加できます。 ドロップダウンの名前は、テンプレートのファイル名に基づいています。
次の例では、3 つのテンプレートが記載されています。
-
dev.md- これは、ファイル名の後に表示される既定のメッセージで示されているように、この pull request に既定で適用された、開発ブランチへのブランチ固有のテンプレートです。 -
additional.md- これは追加のテンプレートです。 -
pull_request_template.md- これは通常、既定のテンプレートですが、この pull request のdev.mdブランチ固有のテンプレートでオーバーライドされました。 既定では追加されていませんが、一覧から選択することで適用できます。
希望の追加のテンプレートの名前を選択して、そのコンテンツを現在の pull request の説明に追加します。
注意
querystring に ?template=name.md を追加することで、一致する既定またはブランチ固有の pull request をオーバーライドする pull request テンプレートを指定できます。