注意

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

PyTorch 贡献指南

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

贡献流程

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

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

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

• **确定您要做什么。** 大多数开源贡献来自那些想要解决自身问题的人。但是，如果您不知道自己想做什么，或者只是想更熟悉这个项目，这里有一些寻找合适任务的技巧

  • 查看问题跟踪器，看看是否有您知道如何解决的问题。其他贡献者确认过的问题往往更值得研究。我们还为一些可能适合新手的 issue 维护了一些标签，例如**bootcamp**和**1hr**，尽管这些标签维护得不是很好。

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

• **确定您更改的范围，如果更改较大，请在 GitHub issue 上征求设计意见。** 大多数拉取请求都很小；在这种情况下，无需告诉我们您想做什么，直接开始干活就行。但是，如果更改较大，通常最好先通过提交 RFC来获得一些设计意见。

  • 如果您不知道更改会有多大，我们可以帮您确定！只需在问题或开发者讨论区上发布即可。

  • 有些功能添加非常标准化；例如，很多人都在 PyTorch 中添加新的运算符或优化器。在这种情况下，设计讨论基本上归结为：“我们需要这个运算符/优化器吗？” 提供其用途的证据，例如在同行评审的论文中使用，或在其他框架中存在，有助于证明这一点。

    • **添加来自最近发布的研究中的运算符/算法**通常是不被接受的，除非有充分的证据表明这项新发布的工作具有突破性的结果，并将最终成为该领域的标准。如果您不确定您的方法属于哪种情况，请先提出一个 issue，然后再实现 PR。

  • 由于 PyTorch 主分支的开发速度非常快，因此核心更改和重构可能很难协调。一定要就基础性或跨领域的更改与我们联系；我们通常可以就如何将此类更改分解成更容易审查的部分提供指导。

• 编写代码！

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

• 打开一个拉取请求。

  • 如果您还没有准备好让拉取请求接受审查，请先创建一个草案拉取请求 - 您可以稍后通过按下“准备审查”按钮将其转换为正式的 PR。您还可以在 PR 的标题前加上“[WIP]”（“工作进行中”），因为它还处于草案阶段。在进行审查时，我们会忽略草案 PR。如果您正在进行一项复杂的更改，最好先从草案开始，因为您需要花时间查看 CI 结果，看看事情是否顺利。

  • 为您的更改找到合适的审查者。我们有一些人会定期查看 PR 队列并尝试审查所有内容，但如果您碰巧知道谁是您补丁所影响的给定子系统的维护者，请随时将他们直接包含在拉取请求中。您可以详细了解可以审查您代码的相关人员。

• 迭代拉取请求，直到它被接受！

  • 我们会尽力减少审查往返的次数，并且仅在出现重大问题时才会阻止 PR。有关拉取请求中最常见的问题，请查看常见错误。

  • 一旦拉取请求被接受并且 CI 通过，您就无需再做任何事情了；我们会为您合并 PR。

入门指南

提出新功能

最好在特定的 issue 中讨论新的功能想法。请尽可能多地提供信息、任何随附的数据以及您提议的解决方案。PyTorch 团队和社区会定期审查新的 issue 和评论，看看他们是否可以提供帮助。如果您对自己的解决方案充满信心，请继续实施。

报告问题

如果您发现了一个问题，请先在代码仓库的现有问题列表中搜索。如果您找不到类似的问题，请创建一个新的 issue。提供尽可能多的信息以重现问题行为。此外，还应包括任何其他见解，例如您期望的行为。

实现功能或修复错误

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

标记为“first-new-issue”、“low”或“medium”优先级的 issue 提供了最佳的切入点，是开始的好地方。

添加教程

pytorch.org 上的大量教程都来自社区本身，我们欢迎更多贡献。要了解更多关于如何贡献新教程的信息，请访问：PyTorch.org 教程贡献指南（GitHub）

改进文档和教程

我们的目标是制作高质量的文档和教程。在极少数情况下，内容中会出现错别字或错误。如果您发现可以修复的内容，请向我们发送拉取请求以供考虑。

请查看“文档”部分，了解我们系统的运作方式。

参与在线讨论

您可以在PyTorch 论坛上找到针对用户的活跃讨论，以及在PyTorch 开发者论坛上找到针对开发者和维护者的活跃讨论。

提交拉取请求以修复未解决的问题

您可以此处查看所有未解决的问题的列表。对 issue 进行评论是引起团队注意的好方法。您可以在这里分享您的想法以及您计划如何解决问题。

对于更具挑战性的问题，团队将就如何最好地解决问题提供反馈和指导。

如果您无法自行解决问题，评论和分享您是否可以重现该问题可以帮助团队识别问题所在。

审查未合并的拉取请求

我们感谢您帮助审查和评论拉取请求。我们的团队努力将未合并的拉取请求数量保持在一个可管理的范围内，如果我们需要更多信息，我们会尽快回复，并且我们会合并我们认为有用的拉取请求。但是，由于人们的兴趣很高，我们始终欢迎大家对拉取请求提出更多意见。

提高代码可读性

提高代码可读性对每个人都有帮助。提交少量涉及少量文件的拉取请求通常比提交大量涉及大量文件的拉取请求要好。在 PyTorch 论坛此处或与您的改进相关的 issue 上发起讨论是最好的开始方式。

添加测试用例以使代码库更加健壮

我们感谢您提供额外的测试覆盖率。

推广 PyTorch

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

分类问题

如果您认为某个问题可以从特定标签或复杂程度中受益，请对该问题发表评论并分享您的意见。如果您认为某个问题的分类不正确，请发表评论并告知团队。

关于开源开发

如果这是您第一次为开源项目做贡献，那么开发过程的某些方面可能对您来说并不寻常。

• **没有办法“认领”问题。**人们通常希望在决定处理某个问题时“认领”该问题，以确保当其他人最终也处理该问题时不会浪费工作。这在开源中并不能很好地运作，因为有些人可能会决定处理某些事情，但最终却没有时间去做。您可以随意以建议的方式提供信息，但最终，我们将采用运行代码和大致共识的方式快速推进。

• **新功能的门槛很高。**与企业环境不同，在企业环境中，编写代码的人隐式地“拥有”代码，并且可以在代码的生命周期内维护代码，一旦拉取请求被合并到开源项目中，它就会立即成为项目所有维护者的集体责任。当我们合并代码时，我们是在说我们（维护者）可以审查后续的更改并对代码进行错误修复。这自然会导致更高的贡献标准。

要避免的常见错误

• **您是否添加了测试？**（或者，如果更改难以测试，您是否描述了您如何测试更改？）

  • 我们要求进行测试有几个动机：

    1. 帮助我们在以后代码被破坏时及时发现

    2. 帮助我们判断补丁一开始是否正确（是的，我们确实审查过代码，但正如 Knuth 所说，“请注意以下代码，因为我没有运行它，只是证明了它的正确性”）

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

• 您的拉取请求是否太长？

  • 我们更容易审查和合并小的拉取请求。审查拉取请求的难度与其规模呈非线性关系。

  • 什么时候可以提交大型拉取请求？如果在 issue 中有相应的讨论，并且得到了将要审查您的差异的人的签字同意，那么这将非常有帮助。我们还可以就如何将大型更改拆分为可单独发布的部分提供建议。同样，如果对拉取请求的内容有完整的描述，这也会有所帮助：如果我们知道里面是什么，就更容易审查代码！

• **对微妙之处的评论？**如果您的代码行为比较微妙，请添加额外的注释和文档，以便我们更好地理解您的代码意图。

• **您是否添加了 hack？**有时，正确的答案是 hack。但通常情况下，我们必须对此进行讨论。

• **您想修改非常核心的组件吗？**为了防止出现重大回归，涉及核心组件的拉取请求会受到额外的审查。在进行重大更改之前，请确保您已经与团队讨论过您的更改。

• **想要添加新功能？**如果您想添加新功能，请在相关 issue 上评论您的意图。我们的团队会尽量对社区发表评论并提供反馈。在构建新功能之前，最好与团队和社区的其他成员进行公开讨论。这有助于我们了解您正在做什么，并增加您的代码被合并的几率。

• **您是否修改了与拉取请求无关的代码？**为了便于代码审查，请在您的拉取请求中只包含与您的更改直接相关的文件。

常见问题解答

• **我如何才能作为审阅者做出贡献？**如果社区开发者能够重现问题、试用新功能或以其他方式帮助我们识别或解决问题，那么这将是非常有价值的。在任务或拉取请求中评论您的环境详细信息将非常有帮助，我们对此表示感谢。

• **CI 测试失败，这意味着什么？**也许您的拉取请求是基于一个损坏的主分支？您可以尝试将您的更改重新基于最新的主分支。您还可以在https://hud.pytorch.org/ 上查看主分支的 CI 的当前状态。

• **哪些更改风险最高？**任何涉及构建配置的更改都是风险很高的区域。除非您事先与团队讨论过，否则请避免更改这些内容。

• **嘿，我的分支上出现了一个提交，这是怎么回事？**有时，其他社区成员会对您的拉取请求或分支提供补丁或修复。这通常是通过 CI 测试所必需的。

关于文档

Python 文档

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

• 网站：https://pytorch.ac.cn/docs

• GitHub：https://github.com/pytorch/pytorch/tree/main/docs

• 服务地址：https://github.com/pytorch/pytorch.github.io/tree/master/docs

C++ 文档

对于 C++ 代码，我们使用 Doxygen 生成内容文件。C++ 文档是在一台特殊的服务器上构建的，生成的文件会被复制到https://github.com/pytorch/cppdocs 代码仓库中，并通过 GitHub Pages 提供服务。

• 网站：https://pytorch.ac.cn/cppdocs

• GitHub：https://github.com/pytorch/pytorch/tree/main/docs/cpp

• 服务地址：https://github.com/pytorch/cppdocs

教程

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

• 网站：https://pytorch.ac.cn/tutorials

• GitHub：https://github.com/pytorch/tutorials

教程构建概述

对于教程，拉取请求 会触发使用 CircleCI 重新构建整个网站，以测试更改的效果。此构建分为 9 个工作构建，总共需要大约 40 分钟。同时，我们使用 make html-noplot 进行 Netlify 构建，该构建在不将笔记本输出呈现到页面中的情况下构建网站，以便快速查看。

拉取请求被接受后，将使用 GitHub Actions 重新构建和部署网站。

贡献新教程

参见 PyTorch.org 教程贡献指南。