使用範本改善提取要求描述

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

撰寫良好的提取要求描述是協助檢閱者瞭解檢閱程式碼時預期狀況的絕佳方式。 它們也是協助追蹤每個變更應完成之事項的絕佳方式，例如測試、新增單元測試，以及更新檔。 提取要求範本可協助您的開發人員建立符合組織標準的絕佳提取要求描述。

本文說明如何開始使用提取要求範本。

注意

提取要求範本可以提供指引，但僅限諮詢。 使用分支原則強制執行最佳做法，例如要求主要等主要分支的提取要求、需要成功建置，以及強制執行必要的檢閱者。 如需詳細資訊，請參閱 分支原則。

什麼是提取要求範本？

提取要求範本是檔案，其中包含在建立提取要求時新增至提取要求描述的 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_template.md 或 pull_request_template.txt 的檔案，並將它儲存在存放庫的預設分支中，並儲存在下列其中一個資料夾中。

• 名為 .azuredevops 的資料夾，包含在存放庫的根資料夾中
• 名為 .vsts 的資料夾，包含在存放庫的根資料夾中
• 名為 docs 的資料夾，包含在存放庫的根資料夾中
• 存放庫的根資料夾

系統會提供多個位置，讓您彈性地儲存提取要求範本。 建立提取要求時，Azure Repos依指定的順序搜尋指定的資料夾，並使用它找到的第一個預設提取要求範本。

在存放庫中建立新的提取要求時，除非套用 分支特定的提取要求範本 ，否則預設提取要求範本的內容會用來預先填入提取要求中的描述欄位。

您可以視需要從 [新增範本] 下拉式清單中選取這些範本，來編輯或新增至此描述，並附加其他提取要求範本。

注意

自動套用預設或分支特定的提取要求範本時，它會取代通常用於預設描述的標準認可訊息。 您可以選取 [ 新增認可訊息] 來將它們新增回。

分支特定提取要求範本

您可以針對以特定分支為目標的提取要求設定分支特定提取要求範本。 若要使用分支特定的提取要求範本來設定您的存放庫，請建立 .txt 或 .md 檔案，名為 您的分支。 名稱必須符合分支名稱的第一層，例如 main 、 dev 、 release 或 feature 。 每次提取要求目標為分支或包含于其中的任何分支時，都會套用每個分支特定的提取要求範本。 例如，如果提取要求以分支或任何 feature/* 分支為目標，則會套用名為 feature.md 的 feature 提取要求範本。

分支特定的提取要求範本必須使用下列資料夾階層，儲存在存放庫的預設分支中： pull_request_template/branches/ 。 這些資料夾必須以存放庫中的下列其中一個資料夾為基礎。

• 名為 .azuredevops 的資料夾，包含在存放庫的根資料夾中
• 名為 .vsts 的資料夾，包含在存放庫的根資料夾中
• 名為 docs 的資料夾，包含在存放庫的根資料夾中
• 存放庫的根資料夾

例如，應該套用至分支中所有提取要求的 dev 分支特定提取要求範本，會命名 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/

就像預設提取要求範本一樣，會提供多個位置，讓您有彈性地儲存分支特定的提取要求範本。 建立提取要求時，Azure Repos依指定之分支特定提取要求範本的順序搜尋指定的資料夾，並使用它找到符合分支名稱的第一個資料夾。 如果找不到分支特定的提取要求範本，Azure Repos接著搜尋預設提取要求範本，如上一個預設提取要求範本一節中所述。

其他提取要求範本

除了預設和分支特定的提取要求範本之外，您還可以設定其他提取要求範本。 這些可以是 .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/

建立提取要求時，您可以從 [ 新增範本 ] 下拉式清單中加以選擇，以附加任何可用的提取要求範本。 下拉式清單中的名稱是以範本的檔案名為基礎。

在下列範例中會列出三個範本。

• dev.md - 這是預設套用至此提取要求至開發分支的分支特定範本，如檔案名之後所列 的預設 訊息所指出。
• additional.md - 這是額外的範本。
• pull_request_template.md - 這通常是預設範本，但此提取要求中的分支特定範本已覆寫 dev.md 。 即使預設未新增，仍可藉由從清單中選取它來套用它。

選取所需的其他範本名稱，將其內容附加至目前的提取要求描述。

注意

您可以藉由附加 ?template=name.md 至 querystring，指定提取要求範本來覆寫任何相符的預設或分支特定提取要求。

另請參閱

• 建立提取要求以檢閱和合併程式碼
• 關於分支和分支原則