评价此页
★ ★ ★ ★ ★

注意

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

PyTorch 贡献指南#

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

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

贡献流程#

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

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

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

  • 确定您要处理的内容。 大多数开源贡献来自有自己需求的人。但是，如果您不知道要处理什么，或者只是想更熟悉该项目，这里有一些关于如何找到合适任务的建议：

    • 浏览 问题跟踪器，看看是否有您知道如何解决的问题。其他贡献者已确认的问题通常是更好的研究对象。我们也为可能适合新人的问题维护了一些标签，例如 **bootcamp** 和 **1hr**，尽管这些标签维护得不太好。

    • 加入我们的 开发讨论区，让我们知道您有兴趣了解 PyTorch。我们非常乐意帮助研究人员和合作伙伴快速掌握代码库。

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

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

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

      • 添加新发布的研究所提出的算子/算法 通常不被接受，除非有压倒性的证据表明这项新发表的工作具有开创性的结果，并最终将成为该领域的标准。如果您不确定您的方法属于哪一类，请先打开一个 issue，然后再实现 PR。

    • 核心更改和重构的协调可能相当困难，因为 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 团队和社区会定期审查新 issues 和评论，他们认为可以提供帮助的地方。如果您对解决方案有信心，请继续实现它。

报告问题#

如果您发现一个问题，请先搜索存储库上的 现有问题列表。如果您找不到类似的问题，则创建一个新的问题。提供尽可能多的信息来重现问题行为。此外，还应包含任何额外的见解，例如您期望的行为。

实现功能或修复 bug#

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

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

添加教程#

pytorch.org 上的许多教程都来自社区本身，我们欢迎更多的贡献。要了解如何贡献新教程，您可以在此处了解更多：GitHub 上的 PyTorch.org 教程贡献指南

改进文档和教程#

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

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

参与在线讨论#

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

提交 Pull Request 来修复开放的 Issue#

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

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

如果您无法自行修复该 issue，通过评论并分享您是否可以重现该 issue，可以帮助团队识别问题区域。

审查开放的 Pull Request#

我们非常感谢您审查和评论 pull request。我们的团队努力使开放 pull request 的数量保持在可管理的范围内，如果我们还需要更多信息，我们会迅速响应，并且我们会合并我们认为有用的 PR。但是，由于关注度很高，额外的眼睛审阅 pull request 总是受欢迎的。

提高代码可读性#

提高代码可读性对每个人都有帮助。提交少量修改几个文件的 pull request 通常比修改很多文件的单个大型 pull request 要好。在 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 request 会受到额外的审查。在进行重大更改之前，请务必与团队讨论您的更改。

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

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

常见问题#

  • 我如何作为审阅者做出贡献？ 社区开发者重现问题、尝试新功能或以其他方式帮助我们识别或排除问题非常有价值。在任务或 pull request 上附带您的环境详细信息会很有帮助且受到赞赏。

  • CI 测试失败，这意味着什么？ 也许您的 PR 基于一个损坏的主分支？您可以尝试将您的更改重新定位到最新的主分支之上。您还可以在 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 构建，该构建在不将 notebook 输出渲染为页面进行快速审查的情况下构建站点。

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

贡献新教程#

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

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