Skip to main content

拉取请求的最佳做法

遵循以下最佳做法可以提高拉取请求和拉取请求审查的一致性及质量。

有关拉取请求创建的最佳做法

创建拉取请求时,请遵循以下最佳做法来确保审查过程更加顺利。 有关拉取请求创建的详细信息,请参阅“创建拉取请求”。

编写小型 PR

创建能够实现单个目的、重点明确的小型拉取请求。 拉取请求越小,进行审查和合并的难度越低,速度越快,引入 bug 的可能性越低,并且可提供更清晰的更改历史记录。

首先审查自己的拉取请求

首先审查、生成和测试自己的拉取请求,然后再提交。 这有利于在其他人开始审查之前发现可能漏掉的错误或错别字。

提供上下文和指导

为拉取请求编写清晰的标题和说明,以便审阅者可以快速了解拉取请求的作用。 在拉取请求正文中包含以下内容:

  • 拉取请求的用途
  • 更改内容的概述
  • 任何其他上下文的链接,例如跟踪问题或以前的对话

为方便审阅者,请说明所需的反馈类型。 例如,是需要快速浏览一下,还是进行更深入的评价?

如果拉取请求包含对多个文件的更改,请向审阅者提供有关文件审查顺序的指导。 建议从何处开始以及如何进行审查。

有关拉取请求管理的最佳做法

如果你是仓库维护者,请执行以下步骤来管理和标准化参与者在仓库中创建的拉取请求。

使用拉取请求模板

借助拉取请求模板,你可以自定义和标准化有人在仓库中创建拉取请求时需要包含的信息。 将拉取请求模板添加到仓库后,项目贡献者会自动在拉取请求正文中看到模板的内容。 有关详细信息,请参阅“为仓库创建拉取请求模板”。

可以使用拉取请求模板来标准化仓库的检查过程。 例如,可以将任务列表添加到模板中,从而包含你希望作者在合并其拉取请求之前完成的一系列任务。 有关详细信息,请参阅“关于任务列表”。

可以请求参与者在其拉取请求正文中包含问题参考,以确保合并拉取请求将会自动关闭问题。 有关详细信息,请参阅“将拉取请求链接到议题”。

定义代码所有者

你可能希望确保始终由特定的个人来审查对仓库中某些代码或文件的更改。 例如,你可能希望始终由团队中的技术写作人员审查 docs 目录中的更改。

可以定义将会负责仓库中代码或文件的个人或团队,以使其成为代码所有者。 当有人打开将会修改代码所有者拥有的文件的拉取请求时,将自动请求代码所有者进行审查。 可以为特定类型的文件或目录以及仓库中的不同分支定义代码所有者。 有关详细信息,请参阅“关于代码所有者”。

使用受保护分支

可以使用受保护分支来防止在满足某些条件之前将拉取请求合并到重要分支,例如 main。 例如,可以要求通过 CI 测试或批准审查。 有关详细信息,请参阅“关于受保护分支”。

使用推送规则集

使用推送规则集,可以阻止对专用或内部存储库的推送,以及对此存储库整个分支网络的推送,具体取决于文件扩展名、文件路径长度、文件和文件夹路径以及文件大小。

推送规则不需要针对任何分支,因为它们会应用于对存储库的每条推送。

推送规则集允许你:

  • 限制文件路径:阻止推送包含指定文件路径更改的提交。

    可以为此使用 fnmatch 语法。 例如,针对 test/demo/**/* 的限制可阻止对 test/demo/ 目录中的文件或文件夹进行任何推送。 针对 test/docs/pushrules.md 的限制可阻止对 pushrules.md 目录中 test/docs/ 文件的专门推送。 有关详细信息,请参阅“创建存储库的规则集”。

  • 限制文件路径长度:阻止推送包含超过指定字符限制的文件路径的提交。

  • 限制文件扩展名:阻止推送包含具有指定文件扩展名的文件的提交。

  • 限制文件大小:阻止推送超过指定文件大小限制的提交。

关于向已创建分支的存储库推送规则集

推送规则适用于存储库的整个分支网络,以确保存储库的每个入口点均受到保护。 例如,如果将已启用推送规则集的存储库创建为分支,则相同的推送规则集也适用于已创建分支的存储库。

对于已创建分支的存储库,只有对推送规则具有旁路权限的人员是根存储库中具有旁路权限的人员。

有关详细信息,请参阅“关于规则集”。

使用自动化工具审查代码样式

在仓库的拉取请求中使用自动化工具(如 Linter)来保持一致的样式,并使代码更易于理解。 使用自动化工具来捕获较小的问题,如拼写错误或样式,让审阅者有更多的时间专注于拉取请求的实质内容。

例如,可以使用 GitHub Actions 设置代码 Linter,以作为持续集成 (CI) 工作流的一部分可在拉取请求上运行。 有关详细信息,请参阅“关于使用 GitHub Actions 进行持续集成”。