Reviewing proposed changes in a pull request

Review commits, file changes, and diffs in pull requests to provide feedback, approve changes, or request updates before merging.

Tool navigation

在本文中

About reviewing pull requests

It's best to review changes in a pull request one file at a time:

  • Examine each individual file changed in the pull request.
  • Leave comments on specific changes.
  • After reviewing a file, mark it as Viewed to collapse it and track your progress.
  • The progress bar in the pull request header shows how many files you've viewed.
  • When you've finished, you can approve the pull request or request changes by submitting your review with a summary comment.

Understanding the purpose of the pull request

Understanding the motivation behind a pull request helps you keep your review targeted and meaningful. It also helps you provide feedback that aligns with the pull request author’s intent and the project's goals.

You have several options to better understand the context and rationale for proposed changes.

Using the pull request sidebar for context

In the pull request sidebar, you can find valuable context, including:

  • Linked issues or discussions: Review these to understand the problems or goals that the pull request aims to address. You can also gather information about background, design decisions, or current debates.
  • Linked projects or milestones: Review how this pull request fits within larger projects or upcoming releases.

Use this information to frame your review and check if the goals of the pull request align with the original intent.

Using 副驾驶聊天 to understand the rationale

You can ask 副驾驶聊天 for help understanding the pull request’s intent or clarifying any part of the change.

  1. At the top right of the pull request page, click the button next to the search bar.

    副驾驶聊天 is displayed, with the pull request attached as context to the prompt window.

  2. In the prompt box, type a question and press Enter. For example, you could enter:

    • What problem does this pull request solve?
    • Why were these changes needed?
    • Summarize the goals of this PR based on the linked issue.
    • How does this PR relate to issue ISSUE-URL?

副驾驶聊天 can help you clarify the bigger picture before you start line-level review.

Starting a review

  1. 在仓库名称下，单击 “Pull requests”****。

    存储库的主页的屏幕截图。 在水平导航栏中，标记为“拉取请求”的选项卡以深橙色标出。

  2. 在拉取请求列表中，单击要审查的拉取请求。

  3. 在拉取请求上，单击“ Files changed”****。

    拉取请求的选项卡的屏幕截图。 “已更改的文件”选项卡以深橙色突出显示。 To change the format of the diff view in this tab, click and choose the unified or split view. The choice you make will apply when you view the diff for other pull requests.

    Screenshot of the "Files changed" tab for a pull request. The "Diff view" menu is outlined in dark orange.

    You can also hide whitespace differences. The choice you make only applies to this pull request and will be remembered the next time you visit this page.

  4. Optionally, filter the files to show only the files you want to review or use the file tree to navigate to a specific file.

  5. 将鼠标悬停在要添加评论的代码行上方，然后单击蓝色的评论图标。

    拉取请求中差异的屏幕截图。 在行号旁边，蓝色加号图标以橙色边框突出显示。

  6. 或者，可以在多行中添加批注。 若要选择一系列行，请单击要批注的第一行的行号，然后向下拖动到最后一行，或按住 Shift 并单击最后一行号。 然后，可以单击要批注的最后一行上的蓝色批注图标。 或者，可以单击要对其添加注释的第一行旁边的蓝色批注图标，然后向下拖动到要对其添加批注的最后一行。

  7. 在评论字段中输入您的评论。

  8. （可选）要提供有关对一行或多行进行特定更改的建议，请单击“”，然后对建议块中的文本进行编辑。

    审核备注框屏幕截图。 用于建议特定更改的文件差异图标以深橙色轮廓显示。

  9. 若要直接对文件进行注释，请单击文件右侧的 ，然后键入注释。

    拉取请求的“文件已更改”页上的映像文件的屏幕截图。 在文件的右侧，以橙色框出了“注释”图标。

  10. When you're done, click Start a review. If you have already started a review, you can click Add review comment.

Before you submit your review, your line comments are pending and only visible to you. You can edit pending comments anytime before you submit your review. To cancel a pending review, including all of its pending comments, click Review changes, then click Abandon review.

Screenshot of the comment field for a review. The "Abandon review" button is outlined in dark orange.

Reviewing dependency changes

If the pull request contains changes to dependencies, you can use the dependency review for a manifest or lock file to see what has changed. You can also check whether the changes introduce security vulnerabilities. See Reviewing dependency changes in a pull request.

  1. 在拉取请求上，单击“ Files changed”****。

    拉取请求的选项卡的屏幕截图。 “已更改的文件”选项卡以深橙色突出显示。

  2. On the right of the header for a manifest or lock file, display the dependency review by clicking the rich diff button.

    Screenshot of the "Files changed" tab of a pull request. The button to display the rich diff, labeled with a file icon, is outlined in dark orange.

  3. 您可能还想查看源差异，因为清单或锁定文件可能会发生变化，但不会更改依赖项，也可能存在 GitHub 无法解析的依赖项，因此，这些依赖项不会显示在依赖项审核中。

    要返回到源差异视图，请单击“”按钮。****

    拉取请求的“已更改的文件”选项卡的屏幕截图。 以橙色框出了用于显示源差异的按钮（显示有代码图标）。

Marking a file as viewed

After you finish reviewing a file, you can mark the file as viewed. The file will collapse. If the file changes after you view the file, it will be unmarked as viewed.

  1. 在拉取请求上，单击“ Files changed”****。

    拉取请求的选项卡的屏幕截图。 “已更改的文件”选项卡以深橙色突出显示。

  2. On the right of the header of the file you've finished reviewing, select Viewed.

    Screenshot of the header of a file. The "Viewed" option is outlined in dark orange.

Submitting your review

After you've finished reviewing all the files you want in the pull request, submit your review.

  1. 在拉取请求上，单击“ Files changed”****。

    拉取请求的选项卡的屏幕截图。 “已更改的文件”选项卡以深橙色突出显示。

  2. 在更改的代码上方，单击“审阅更改”。

    拉取请求的“已更改的文件”选项卡的屏幕截图。 “审查更改”按钮用深橙色框标出。

  3. 输入评论，概述您对拟议更改的反馈。

  4. Select the type of review you'd like to leave:

    • Select Comment to leave general feedback without explicitly approving the changes or requesting additional changes.
    • Select Approve to submit your feedback and approve merging the changes proposed in the pull request.
    • Select Request changes to submit feedback that must be addressed before the pull request can be merged.

  5. 单击“提交审查”。

提示

  • “请求更改”选项纯粹是信息性的，除非规则集或经典分支保护规则配置了“要求拉取请求”选项，否则不会阻止合并。 如果配置了该选项，并且具有对存储库的 admin、owner 或 write 访问权限的协作者提交请求更改的审查，则在同一协作者提交另一次要求批准拉取请求中更改的审查之前，拉取请求不能合并。
  • 即使没有获得批准审查，或者请求更改的审查者离开了组织或者联系不上，仓库所有者和管理员也可合并拉取请求。
  • 如果同时启用了必需审查和过期审查，并且代码修改提交已推送到批准的拉取请求分支，则批准将予驳回。 拉取请求必须经过再次审查和批准才可合并。
  • 当多个打开的拉取请求时分别有指向同一提交的头部分支时，如果一个或两者有待定或被拒绝的审查，你将无法合并它们。
  • 拉取请求作者无法批准自己的拉取请求。

Further reading