评价此页
★ ★ ★ ★ ★

注意

此页面已被弃用。请参阅 PyTorch Wiki 上的 贡献指南。

PyTorch Contribution Guide#

创建于: 2019 年 3 月 11 日 | 最后更新于: 2025 年 4 月 27 日

PyTorch 是一个 GPU 加速的 Python 张量计算包，用于通过基于磁带的自动微分系统构建深度神经网络。

贡献流程#

PyTorch 组织受 PyTorch Governance 管辖，贡献的技术指南可在 CONTRIBUTING.md 中找到。

PyTorch 的开发流程涉及核心开发团队与社区之间大量的开放式讨论。

PyTorch 的运行方式与 GitHub 上的大多数开源项目类似。但是，如果您以前从未为开源项目做出过贡献，以下是基本流程。

  • 确定您要处理的内容。 大多数开源贡献来自人们解决自身痛点。但是，如果您不知道要处理什么，或者只是想更多地了解该项目，以下是一些查找合适任务的技巧。

    • 查看 issue tracker，看看是否有您知道如何修复的 issue。由其他贡献者确认的 issue 通常更值得研究。我们还为可能适合新人的 issue 维护了一些标签，例如 **bootcamp** 和 **1hr**，尽管这些标签维护得不太好。

    • 加入我们的 dev discuss，让我们知道您有兴趣了解 PyTorch。我们非常乐意帮助研究人员和合作伙伴熟悉代码库。

  • 确定您更改的范围，如果较大，请就设计发表意见。 大多数 pull request 都很小；在这种情况下，无需告知我们您想做什么，直接开始即可。但如果更改很大，通常最好通过 提交 RFC 来先获得一些设计反馈。

    • 如果您不知道更改会有多大，我们可以帮助您弄清楚！只需在 issues 或 dev discuss 上发帖讨论。

    • 一些功能添加非常标准化；例如，许多人向 PyTorch 添加了新的运算符或优化器。在这种情况下，设计讨论主要集中在“我们想要这个运算符/优化器吗？”提供其效用的证据，例如在同行评审论文中的使用，或在其他框架中存在，有助于做出此决定。

      • 添加最近发布的、未经验证的研究中的算子/算法 通常不被接受，除非有压倒性的证据表明这项新发布的工作具有突破性的结果，并最终将成为该领域的标准。如果您不确定您的方法属于哪一类，请在实施 PR 之前先打开一个 issue。

    • 核心更改和重构可能很难协调，因为 PyTorch 主分支的开发速度非常快。请务必就根本性或跨领域更改进行沟通；我们通常可以就如何将此类更改分阶段进行更易于审查的部分提供指导。

  • 编写代码！

    • 有关使用 PyTorch 的技术方面的建议，请参阅 CONTRIBUTING.md 文件。

  • 提交 pull request。

    • 如果您还没有准备好让 pull request 被审查，请先创建一个草稿 pull request——稍后可以通过按“Ready for review”按钮将其转换为完整的 PR。您也可以在草稿中时，在 PR 标题前加上“[WIP]”（“work in progress”）。我们在进行审查时会忽略草稿 PR。如果您正在处理一项复杂的更改，最好先将其设为草稿，因为您需要花时间查看 CI 结果，以确定是否成功。

    • 为您的更改找到合适的审查者。我们有一些人会定期检查 PR 队列并尝试审查所有内容，但如果您碰巧知道您所修补的某个子系统的维护者是谁，请随时直接在 pull request 中提及他们。您可以进一步了解 可能审查您代码的相关人员。

  • 对 pull request 进行迭代，直到被接受！

    • 我们将尽力减少审查往返次数，仅在存在重大问题时才阻止 PR。有关 pull request 中最常见的问题，请参阅 常见错误。

    • 一旦 pull request 被接受且 CI 通过，您就不需要做任何其他事情了；我们将为您合并 PR。

入门#

提议新功能#

新功能想法最好在特定的 issue 上讨论。请包含尽可能多的信息，任何相关的支持数据以及您提出的解决方案。PyTorch 团队和社区会定期审查新 issue 和评论，他们认为自己可以提供帮助。如果您对自己的解决方案有信心，就动手实现它吧。

报告问题#

如果您发现了问题，请首先搜索存储库中的 现有 issue 列表。如果您找不到类似的 issue，请创建一个新的。提供尽可能多的信息来重现问题行为。另外，包括任何额外的见解，如您期望的行为。

实现功能或修复 Bug#

如果您想修复特定的 issue，最好在单个 issue 上发表您的意图。但是，我们不会锁定或分配 issue，除非我们之前与该开发人员有过合作。最好在 issue 上开始对话并讨论您提出的解决方案。PyTorch 团队可以提供节省时间的指导。

标记为 first-new-issue、low 或 medium priority 的 issue 是最佳的切入点，也是开始的好地方。

添加教程#

pytorch.org 上的大部分教程都来自社区本身，我们欢迎额外的贡献。要了解有关如何贡献新教程的更多信息，请在此处了解更多：GitHub 上的 PyTorch.org 教程贡献指南

改进文档和教程#

我们致力于提供高质量的文档和教程。偶尔会出现内容中的拼写错误或 bug。如果您发现可以修复的地方，请提交 pull request 供我们考虑。

请查看 文档 部分，了解我们的系统如何工作。

参与在线讨论#

您可以在 PyTorch 讨论论坛（面向用户）以及 PyTorch 开发讨论论坛（面向开发者和维护者）上找到活跃的讨论。

提交 Pull Requests 修复开放的 Issue#

您可以在 此处 查看所有开放 issue 的列表。在 issue 上发表评论是引起团队注意的好方法。您可以在此处分享您的想法以及如何解决该 issue。

对于更具挑战性的 issue，团队将提供反馈和指导，说明如何最佳地解决该 issue。

如果您无法自行修复该 issue，发表评论并告知我们您是否可以重现该 issue，可以帮助团队识别问题区域。

审查开放的 Pull Requests#

我们感谢您在审查和评论 pull requests 方面的帮助。我们的团队努力将开放 pull requests 的数量保持在可控范围内，如果我们还需要更多信息，会迅速做出回应，并且我们会合并我们认为有用的 PR。但是，由于兴趣很高，额外的关注总是受欢迎的。

提高代码可读性#

提高代码可读性对每个人都有益。通常最好提交少量触及少数文件的 pull requests，而不是大量触及多个文件的 pull requests。在 PyTorch 论坛 此处 或与您的改进相关的 issue 上发起讨论是开始的最佳方式。

添加测试用例以增强代码库的健壮性#

我们欢迎更多的测试覆盖。

推广 PyTorch#

您在项目、研究论文、文章、博客或互联网上的普遍讨论中使用 PyTorch，有助于提高 PyTorch 和我们不断壮大的社区的知名度。请联系 marketing@pytorch.org 以获得市场支持。

问题分类#

如果您认为某个 issue 可以受益于特定的标签或复杂性级别，请在 issue 上发表评论并分享您的意见。如果您认为某个 issue 分类不当，请发表评论并告知团队。

关于开源开发#

如果这是您第一次为开源项目做出贡献，开发过程的某些方面可能会让您感到陌生。

  • 无法“认领”issue。 人们经常希望在决定处理某个 issue 时“认领”它，以确保不会浪费工作，因为其他人最终会处理它。这在开源项目中并不太奏效，因为有人可能会决定处理某件事，但最终没有时间去做。请随时提供咨询性信息，但归根结底，我们将以可运行的代码和广泛的共识来快速推进。

  • 新功能的要求很高。 与企业环境不同，在企业环境中，编写代码的人隐式地“拥有”它，并可以期望在其生命周期内对其负责。一旦 pull request 被合并到开源项目中，它就立即成为项目所有维护者的集体责任。当我们合并代码时，我们表示我们，即维护者，可以审查后续的更改并对代码进行 bug 修复。这自然会导致更高的贡献标准。

常见错误避免#

  • 您是否添加了测试？ (或者，如果更改难以测试，您是否描述了如何测试您的更改？)

    • 我们有几个理由要求进行测试

      1. 帮助我们判断以后是否会破坏它

      2. 帮助我们判断补丁是否正确 (是的，我们审查了它，但正如 Knuth 所说，“警惕以下代码，因为我没有运行它，只是证明了它的正确性”)

    • 什么时候可以不添加测试？有时更改无法方便地进行测试，或者更改非常明显正确（且不太可能被破坏），因此可以不进行测试。相反，如果更改似乎可能（或已知可能）被意外破坏，那么投入时间制定测试策略就很重要。

  • 您的 PR 是否太长？

    • 我们更容易审查和合并小型 PR。审查 PR 的难度与其大小呈非线性增长。

    • 什么时候可以提交大型 PR？如果有一个相应的 issue 设计讨论，并且得到了将审查您 diff 的人的批准，这将非常有帮助。我们还可以就如何将大型更改分解成可单独发布的部件提供建议。同样，如果对 PR 的内容有完整的描述，那将非常有帮助：了解内容后更容易审查代码！

  • 关于细微之处的注释？ 在您的代码行为很微妙的情况下，请包含额外的注释和文档，以便我们更好地理解您的代码意图。

  • 您是否添加了 hack？ 有时，正确的答案是一个 hack。但通常，我们需要对此进行讨论。

  • 您想触及一个非常核心的组件吗？ 为防止重大回归，触及核心组件的 pull requests 会受到额外的审查。在进行重大更改之前，请确保您已与团队讨论过您的更改。

  • 想添加新功能？ 如果您想添加新功能，请在相关 issue 上说明您的意图。我们的团队会尝试评论并向社区提供反馈。最好在构建新功能之前与团队和社区进行公开讨论。这有助于我们了解您正在做什么，并增加了被合并的机会。

  • 您是否触及了与 PR 无关的代码？ 为了便于代码审查，请仅在您的 pull request 中包含与您的更改直接相关的文件。

常见问题解答#

  • 我如何作为审查者贡献？ 社区开发者重现问题、试用新功能或以其他方式帮助我们识别或排除问题非常有价值。在任务或 pull requests 上评论您的环境详细信息会有所帮助并受到赞赏。

  • CI 测试失败，这是什么意思？ 也许您的 PR 基于一个损坏的主分支？您可以尝试将您的更改变基（rebase）到最新的主分支上。您也可以在 https://hud.pytorch.org/ 查看主分支 CI 的当前状态。

  • 风险最高的更改是什么？ 任何触及构建配置的内容都是高风险区域。请避免更改这些内容，除非您事先与团队进行了讨论。

  • 嘿，我的分支上出现了一个 commit，这是怎么回事？ 有时其他社区成员会为您的 pull request 或分支提供补丁或修复。这通常是让 CI 测试通过所必需的。

关于文档#

Python 文档#

PyTorch 文档使用 Sphinx 从 Python 源代码生成。生成的 HTML 会被复制到 pytorch.org/docs 的主分支的 docs 文件夹中，并通过 GitHub pages 提供服务。

C++ 文档#

对于 C++ 代码，我们使用 Doxygen 来生成内容文件。C++ 文档在一个特殊服务器上构建，并将生成的文件复制到 pytorch/cppdocs 仓库，并通过 GitHub pages 提供服务。

教程#

PyTorch 教程是用于帮助理解如何使用 PyTorch 来完成特定任务或理解更全面的概念的文档。教程使用 Sphinx-Gallery 从可执行的 Python 源代码文件或 reStructuredText (rst) 文件构建。

教程构建概述#

对于教程，pull requests 会触发使用 CircleCI 的整个网站的重建，以测试更改的效果。此构建被分片成 9 个工作器构建，总共需要大约 40 分钟。同时，我们使用 _make html-noplot_ 进行 Netlify 构建，它会在不将笔记本输出渲染到页面以供快速审查的情况下构建网站。

PR 被接受后，网站将使用 GitHub Actions 进行重建和部署。

贡献新教程#

请参阅 PyTorch.org 教程贡献指南。

在此页面上
在 GitHub 上编辑
显示源代码
PyTorch 库