创建拉取请求

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

Visual Studio 2019 | Visual Studio 2022

创建更改、评审和合并 Git 存储库中的代码的拉取请求 (PR)。 可以从上游存储库中的分支或从存储库的分支中的分支创建 PR。 团队可以评审 PR 并提供有关更改的反馈。 审阅者可以逐步执行建议的更改、留下注释,并投票批准或拒绝 PR。 根据分支策略和其他要求,PR 可能需要满足各种条件,然后你才能完成 PR 并将更改合并到目标分支。

有关 PR 准则和管理注意事项,请参阅关于拉取请求

先决条件

  • 必须在项目上启用 Repos。 如果 Repos 中心和关联页面未显示,请参阅打开或关闭 Azure DevOps 服务以重新启用 Repos。

  • 若要查看或评审 PR,必须是 Azure DevOps 项目的成员,具有基本访问级别或更高级别。

  • 若要参与 PR,必须是“读取者”安全组的成员或具有相应的权限。

  • 若要创建和完成 PR,必须是“参与者”安全组的成员或具有相应的权限。

    注意

    对于公共项目,被授予利益干系人访问权限的用户对 Azure Repos 具有完全访问权限。

  • 必须在项目上启用 Repos。 如果 Repos 中心和关联页面未显示,请参阅打开或关闭 Azure DevOps 服务以重新启用 Repos。
  • 要查看或评审 PR,必须是 Azure DevOps 项目的成员,具有基本访问级别或更高级别。 如果你不是项目成员,请添加为成员
  • 若要创建和完成 PR,在要更改的项目中,必须是“参与者”安全组的成员或具有相应的权限。
  • 若要参与 PR,必须是“读取者”安全组的成员或具有相应的权限。
  • 若要创建和完成 PR,必须是“参与者”安全组的成员或具有相应的权限。
  • 若要查看或评审 PR,必须是 Azure DevOps 项目的成员,具有基本访问级别或更高级别。 如果你不是项目成员,请添加为成员
  • 若要参与 PR,必须是“读取者”安全组的成员或具有相应的权限。

创建拉取请求

可以从 Azure DevOps 项目网站、Visual Studio 或 Azure DevOps CLI 创建新 PR。

在 Azure DevOps 项目网站中,可从以下位置创建新 PR:

从“拉取请求”页创建 PR

可以从 Web 上项目的“拉取请求”页为任何分支创建 PR。

  1. 在“Repos”>“拉取请求”页上,选择右上角的“新建拉取请求”。

    “新建拉取请求”按钮的屏幕截图。

  2. 选择包含更改的分支以及要将更改合并到其中的分支,例如主分支。

    Azure Repos 中 PR 的源分支和目标分支的屏幕截图。

  3. 输入 PR 详细信息并创建 PR。

从推送的分支创建 PR

推送或更新功能分支后,Azure Repos 显示创建 PR 的提示。

  • 在“拉取请求”页上:

    在 Azure Repos 中的“拉取请求”选项卡上显示创建 PR 的提示的屏幕截图。

  • 在“文件”页上:

    在 Azure Repos 中的“文件”选项卡上显示创建 PR 的提示的屏幕截图。

选择“创建拉取请求”,转到可在其中输入 PR 详细信息和创建 PR 的页面。

推送或更新功能分支后,Azure Repos 提示你在 Web 上的“代码”视图中创建 PR。 此提示显示在“拉取请求”和“文件”上。

在 Azure Repos 中的“拉取请求”选项卡上显示创建 PR 的提示的屏幕截图。

在 Azure Repos 中的“文件”选项卡上显示创建 PR 的提示的屏幕截图。

选择“创建拉取请求”,转到可在其中输入 PR 详细信息和创建 PR 的页面。

从链接的工作项创建 PR

可以直接从链接到分支的 Azure Boards 工作项创建 PR。

  1. 在 Azure Boards 中,从“工作”视图中的“积压工作”或“查询”中,打开链接到分支的工作项。

  2. 在工作项的“开发”区域中,选择“创建拉取请求”。

    从具有链接分支的工作项的“开发”区域创建 PR 的屏幕截图。

该链接会将你转到一个页面,你可以在其中输入 PR 详细信息并创建 PR。

使用挑拣添加更新

可使用挑拣将提交从一个分支复制到另一个分支。 与合并或变基不同,挑拣仅引入所选提交中的更改,而不是分支中的所有更改。

若要从已完成的 PR 中挑拣更改,请在 PR 的“概述”页上选择“挑拣”。 若要从活动 PR 复制更改,请从 PR 的“更多选项”菜单中选择“挑拣”。 此操作使用复制的更改创建一个新分支。 然后,可以从新分支创建新 PR。 有关详细说明,请参阅使用挑拣复制更改

切换拉取请求的源分支和目标分支

在第一次保存 PR 之前,可以通过选择分支名称旁边的“切换源分支和目标分支”图标来切换 PR 的源分支和目标分支。 PR 处于活动状态后,此图标将消失,但你仍然可以更改 PR 的目标分支

“切换源分支和目标分支”图标的屏幕截图。

使用拉取请求模板

拉取请求模板是一个文件,其中包含在创建 PR 时填充 PR 说明的 Markdown 文本。 良好的 PR 说明告知 PR 审阅者预期的内容,有助于跟踪添加单元测试和更新文档等任务。 团队可以创建一个默认的 PR 模板,用于向存储库中的所有新 PR 说明添加文本。 此外,你还可以从特定于分支的模板或团队定义的其他模板中进行选择。 有关创建和使用 PR 模板的详细信息,请参阅使用模板改进拉取请求说明

如果存储库具有默认模板,则存储库中的所有 PR 在创建时都有默认模板的说明文本。 若要添加其他模板,请选择“添加模板”,然后从下拉列表中选择一个模板。 可以编辑说明中的模板文本、将其删除或添加其他文本。

创建 PR 时显示“添加模板”的屏幕截图。

创建草稿 PR

如果 PR 尚未准备好进行评审,可以创建草稿 PR 来指示正在进行的工作。 当 PR 准备好进行评审时,可以发布它,然后开始或继续完整的评审过程。

草稿 PR 与已发布的 PR 具有以下差异:

  • 生成验证策略不会自动运行。 可以通过选择 PR 中的“更多选项”菜单,手动将生成验证排队。

  • 在草稿模式下,投票处于禁用状态。

  • 不会自动添加必需的审阅者。 通知仅发送给显式添加到草稿 PR 的审阅者。

  • 草稿 PR 显示在 PR 列表中,带有“草稿”徽章。

    显示 PR 列表中的草稿 PR 的屏幕截图。

注意

创建草稿 PR 需要 Azure DevOps Server 2019.1 更新或更高版本。

若要创建草稿 PR,请选择“创建”旁边的箭头,然后在创建 PR 时选择“创建为草稿”。 无需使用 WIP 或 DO NOT MERGE 等标题前缀。

显示“创建为草稿 PR”的屏幕截图。

准备好评审并完成 PR 时,请选择 PR 中右上角的“发布”。 发布 PR 会分配必需的审阅者、评估策略并启动投票。

显示一个 PR 的“发布”的屏幕截图。

若要将现有已发布的 PR 更改为草稿,请选择“标记为草稿”。 将 PR 标记为草稿会删除所有现有投票。

显示“标记为草稿”的屏幕截图。

注意

此功能需要 Azure DevOps Server 2019.1 更新或更高版本。

添加或编辑拉取请求标题和说明

在“新建拉取请求”页上,输入更改的标题和详细说明,使其他人可以了解更改所解决的问题。 与现有 PR 一样,在新 PR 中,可以在单独的选项卡上看到 PR 中的“文件”和“提交”。 可以添加审阅者、链接工作项并向 PR 添加标记。

准备好评审更改时,选择“创建”以创建 PR。

显示创建新 PR 的屏幕截图。

向新 PR 添加详细信息。

如果在创建 PR 时没有准备好所有工作项、审阅者或详细信息,请不要担心。 可以在创建 PR 后添加或更新这些项。

编辑 PR 标题和说明

使 PR 标题和说明保持最新状态,以便审阅者可以了解 PR 中的更改。

可以通过选择当前标题并更新文本来更新现有 PR 的标题。 选择“保存”图标以保存更改,或选择“撤消”图标以放弃更改。

通过选择“说明”部分中的“编辑”图标来编辑 PR 说明。

显示编辑 PR 标题并选择说明“编辑”按钮的屏幕截图。

向拉取请求添加审阅者

可以在新的或现有的 PR 的“审阅者”部分中添加审阅者。 还可以将现有的可选审阅者设置为必需审阅者,或者将必需审阅者更改为可选审阅者或将其删除(除非策略需要这些审阅者)。

分支策略可以要求最少数量的审阅者,或者在 PR 中自动包括某些可选或必需的审阅者。 不能删除分支策略所需的审阅者。 可以将分支策略可选审阅者更改为必需审阅者,或删除这些审阅者。

若要查看自动添加审阅者的分支策略,请在 PR 的“概述”页的“审阅者”部分,右键单击该审阅者旁边的“更多选项”。

显示分支策略自动包含的审阅者的“查看策略”的屏幕截图。

如果要评审 PR 的用户或组不是项目的成员,则需要先将其添加到项目中,然后才能将其添加为审阅者。

向新 PR 添加审阅者:

  1. 在“新建拉取请求”页上的“审阅者”下,选择“搜索要添加为审阅者的用户和组”。
  2. 输入姓名或电子邮件地址时,下拉列表会显示匹配的用户和组的列表。 从列表中选择要添加为可选审阅者的姓名。
  3. 若要添加必需审阅者,请选择“添加必需审阅者”,然后选择“搜索以添加必需的审阅者”以搜索并选择姓名。

向新 PR 添加审阅者的屏幕截图。

向现有 PR 添加审阅者:

  1. 在“概述”页的“审阅者”部分中,选择“添加”,然后选择“必需审阅者”或“可选审阅者”。

    拉取请求概述

  2. 输入姓名或电子邮件地址时,将显示匹配的用户或组的列表。 选择要添加为审阅者的姓名。

    添加 PR 审阅者。

若要在必需和可选之间更改审阅者,或删除审阅者,请选择审阅者姓名右侧的“更多选项”。 若要查看指定为审阅者的组或团队的成员身份,请选择该组的图标。

向 PR 添加审阅者:

  1. 在 PR 中选择“概述”选项卡。

    PR 概述

  2. 选择“审阅者”区域中的“添加”按钮。

  3. 输入要添加到 PR 审阅者列表的用户名或组名称。 如果用户不是项目的成员,则需要添加他们

  4. 输入姓名或电子邮件地址时,将显示匹配的用户或组的列表。 从列表中选择用户或组,将其添加为审阅者。

    添加 PR 审阅者

将工作项链接到新 PR:

  1. 在“新建拉取请求”页上,在“要链接的工作项”下,选择“按 ID 或标题搜索工作项”。
  2. 开始输入工作项 ID 或标题,然后从显示的下拉列表中选择要链接的工作项。 按标题搜索返回按状态筛选的工作项;将排除状态为 “已完成 ”和“ 已删除” 状态的所有工作项。 这些工作项还按日期和用户进行筛选,仅显示过去 30 天内创建或更新的项目,并且它们应由当前用户创建、分配或授权。

将工作项链接到现有 PR:

  1. 在 PR 的“概述”选项卡上的“工作项”区域中,选择“+”。

    显示选择“概述”选项卡和“工作项”部分的屏幕截图。

  2. 输入工作项的 ID 或搜索工作项标题。 从显示的列表中选择工作项。

通过选择工作项旁边的“x”图标删除工作项链接。 删除链接只会删除工作项和 PR 之间的链接。 在分支中创建的链接或从提交创建的链接保留在工作项中。

将工作项链接到 PR:

  1. 在 PR 中选择“概述”选项卡。

    显示选择“概述”选项卡和“链接项”按钮的屏幕截图。

  2. 选择“工作项”区域中的“添加”按钮。 PR 中的“添加”图标

  3. 输入工作项的 ID,或搜索标题与文本匹配的工作项。 从显示的列表中选择工作项。 按标题搜索返回按状态筛选的工作项;将排除状态为“ 已完成 ”和“ 已删除 ”状态的所有工作项。 这些工作项还按日期和用户进行筛选,仅显示在过去 30 天内创建或更新的项目,并且应由当前用户创建、分配或授权这些工作项。

通过选择将鼠标悬停在该工作项上时显示的“删除”按钮来删除工作项链接。 “删除”按钮 删除链接只会删除工作项和 PR 之间的链接。 在分支中创建的链接或从提交创建的链接保留在工作项中。

将工作项链接到 PR:

  1. 在 PR 中选择“概述”。

    在 PR 中选择“概述”。

  2. 选择“工作项”区域中的“添加”按钮。

  3. 输入工作项的 ID,或搜索标题与文本匹配的工作项。 从显示的列表中选择工作项。 按标题搜索返回按状态筛选的工作项;将排除状态为“ 已完成 ”和“ 已删除 ”状态的所有工作项。 这些工作项还按日期和用户进行筛选,仅显示在过去 30 天内创建或更新的项目,并且应由当前用户创建、分配或授权这些工作项。

通过选择将鼠标悬停在该工作项上时显示的“删除”按钮来删除工作项链接。 “删除”图标 删除链接只会删除工作项和 PR 之间的链接。 在分支中创建的链接或从提交创建的链接保留在工作项中。

向拉取请求添加标记

使用标记显示重要详细信息并帮助组织 PR。 标记可以向审阅者传达额外信息,例如 PR 仍是一项正在进行的工作,或者是一个即将发布的版本的修补程序。

显示带标记的 PR 的屏幕截图。

若要在创建 PR 时添加标记,请在“标记”部分键入标记名称。 创建 PR 后,可以在“标记”部分中管理标记。

突出显示 PR 的“标记”部分的屏幕截图。

向拉取请求添加标签

可以使用标签向审阅者传达有关 PR 的额外信息。 也许 PR 仍是一项正在进行的工作,或者是一个即将发布的版本的修补程序。 使用标签传达重要详细信息并帮助组织 PR。

注意

使用 PR 标签需要 TFS 2018.2 或更高版本。

显示带标签的 PR 的屏幕截图。

若要在创建 PR 时添加标签,请选择“添加标签”。 创建 PR 后,可以在“标签”部分中管理其标签。

添加 PR 标签

向拉取请求添加附件

可以在创建期间或之后将文件(包括图像)附加到 PR。 选择“说明”字段下的回形针图标,或将文件直接拖放到 PR 的“说明”字段中。

显示在创建过程中将文件附加到 PR 的“说明”的屏幕截图。

更改活动拉取请求的目标分支

对于大多数团队,几乎所有的 PR 都以默认分支(例如 maindevelop)为目标。 如果有时需要以不同的分支为目标,很容易在创建 PR 时忘记更改目标分支。 如果发生这种情况,可以更改活动 PR 的目标分支:

  1. 在 PR 的“概述”页上选择右上角的“更多操作”,然后从下拉菜单中选择“更改目标分支”。
  2. 在“更改目标分支”窗格中,选择“选择目标分支”,选择新分支,然后选择“更改”。

通过电子邮件向利益干系人发送拉取请求通知

可以通过电子邮件共享拉取请求,以通知审阅者并与团队成员通信。 共享 PR:

  1. 在 PR 的“概述”页上选择“更多选项”,然后选择“共享拉取请求”。

    显示在 PR 的“概述”页上选择“共享拉取请求”的屏幕截图。

  2. 在“共享拉取请求”屏幕上,通过在“收件人:”字段中键入收件人的姓名并从显示的用户名中进行选择来添加收件人。 还可以删除收件人。

  3. 在“注释(可选)”字段中添加可选消息,然后选择“发送”。 收件人将收到一封需要他们注意且链接到 PR 的电子邮件。

注意

如果使用内置电子邮件功能,则只能将电子邮件发送到项目成员的个人地址。 不支持将团队组或安全组添加到“收件人:”行。 如果添加系统无法识别的电子邮件帐户,则会收到一条消息,提示一个或多个电子邮件收件人无权读取已邮寄的拉取请求。

若要使电子邮件功能正常工作,Azure DevOps Server 的管理员必须配置 SMTP 服务器

后续步骤