使用模板改进拉取请求描述

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

编写良好的拉取请求描述是帮助审阅者了解审阅代码时的预期内容的好办法。 它们也是帮助跟踪应对每个更改执行的操作（如测试、添加单元测试和更新文档）的好办法。 拉取请求模板可帮助开发人员创建符合组织标准的出色拉取请求描述。

本文介绍如何开始使用拉取请求模板。

注意

拉取请求模板可以提供指导，但仅供参考。 使用分支策略强制执行最佳做法，例如要求针对关键分支（如 main）的拉取请求、要求成功生成以及强制要求所需的审阅者批准。 有关详细信息，请参阅分支策略。

什么是拉取请求模板？

拉取请求模板是包含 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 允许你创建以下类型的拉取请求模板：

• 默认拉取请求模板，自动应用于存储库中的所有新拉取请求，除非被分支特定拉取请求模板替代
• 分支特定拉取请求模板，自动应用于针对特定分支的拉取请求
• 附加拉取请求模板，拉取请求创建者可以选择性添加

拉取请求模板的类型由其文件名和文件夹位置决定，如以下部分所述。 文件名和文件夹位置不区分大小写，但它们必须位于存储库的默认分支中。

注意

所有拉取请求模板文件必须位于存储库的默认分支（通常为 main）中。 仅使用默认分支中的拉取请求模板文件。

默认拉取请求模板

创建新的拉取请求时，默认拉取请求模板会自动应用于描述字段。 若要使用默认拉取请求模板配置存储库，请创建一个名为 pull_request_template.md 或 pull_request_template.txt 的文件，并将其保存在存储库默认分支中的以下其中一个文件夹中。

• 名为 .azuredevops 的文件夹，包含在存储库的根文件夹中
• 名为 .vsts 的文件夹，包含在存储库的根文件夹中
• 名为 docs 的文件夹，包含在存储库的根文件夹中
• 存储库的根文件夹

提供了多个位置，以便你灵活地存储拉取请求模板。 创建拉取请求时，Azure Repos 将按给定顺序搜索指定的文件夹，并使用找到的第一个默认拉取请求模板。

在存储库中创建新的拉取请求时，除非应用分支特定拉取请求模板，否则将使用默认拉取请求模板的内容来预填充拉取请求中的描述字段。

可以编辑或添加到此描述中，并根据需要追加附加拉取请求模板，方法是从“添加模板”下拉列表中选择它们。

注意

当自动应用默认或分支特定拉取请求模板时，它将替换通常用于默认描述的标准提交消息。 可以通过选择“添加提交消息”重新添加它们。

分支特定拉取请求模板

可为针对特定分支的拉取请求配置分支特定拉取请求模板。 若要使用分支特定拉取请求模板配置存储库，请创建以分支命名的 .txt 或 .md 文件。 该名称必须与分支名称的第一级匹配，例如 main、dev、release 或 feature。 每当拉取请求针对该分支或其下包含的任何分支时，都会应用每个分支特定拉取请求模板。 例如，如果拉取请求针对 feature 分支或任何 feature/* 分支，则将应用名为 feature.md 的拉取请求模板。

分支特定拉取请求模板必须使用以下文件夹层次结构保存在存储库的默认分支中：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 - 这是默认应用于针对 dev 分支的此拉取请求的分支特定模板，如文件名后面列出的默认消息所指示。
• additional.md - 这是一个附加模板。
• pull_request_template.md - 这通常是默认模板，但在此拉取请求中，它已被 dev.md 分支特定模板替代。 即使默认未添加，仍可通过从列表中选择它来进行应用。

选择所需附加模板的名称，将其内容追加到当前拉取请求描述中。

注意

可以通过将 ?template=name.md 追加到查询字符串来指定拉取请求模板，以替代任何匹配的默认或分支特定拉取请求。

另请参阅

• 创建查看和合并代码的拉取请求
• 关于分支和分支策略