注意

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

PyTorch 贡献指南

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

贡献流程

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

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

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

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

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

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

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

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

  • 一些功能添加非常标准化；例如，很多人向 PyTorch 添加新的运算符或优化器。在这些情况下，设计讨论主要归结为“我们是否需要此运算符/优化器？” 为其效用提供证据，例如在同行评审的论文中使用，或在其他框架中存在，在提出这种情况时会有所帮助。

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

  • 核心更改和重构可能很难协调，因为 PyTorch 主分支的开发节奏非常快。一定要联系关于基本或交叉更改；我们通常可以提供关于如何将此类更改分阶段分解为更易于审查的部分的指导。

• 编写代码！

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

• 打开拉取请求。

  • 如果您尚未准备好审查拉取请求，请先创建草稿拉取请求 - 您稍后可以通过按“准备审查”按钮将其转换为完整的 PR。您也可以在 PR 的标题前加上“[WIP]”（“正在进行中”），同时它仍处于草稿状态。在进行审查时，我们将忽略草稿 PR。如果您正在进行复杂的更改，最好以草稿开始，因为您需要花费时间查看 CI 结果以查看是否一切正常。

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

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

  • 我们将尽力减少审查往返次数，并且仅在存在重大问题时阻止 PR。对于拉取请求中最常见的问题，请查看要避免的常见错误。

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

入门

提出新功能

新功能想法最好在特定问题上讨论。请尽可能多地包含信息、任何随附数据以及您提出的解决方案。PyTorch 团队和社区经常审查他们认为可以提供帮助的新问题和评论。如果您对自己的解决方案充满信心，请继续实施。

报告问题

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

实施功能或修复错误

如果您想修复特定问题，最好在个别问题上评论您的意图。但是，除非我们以前与开发人员合作过，否则我们不会锁定或分配问题。最好在问题上发起对话并讨论您提出的解决方案。PyTorch 团队可以提供指导，从而节省您的时间。

标记为 first-new-issue、low 或 medium 优先级的问题提供了最佳的入口点，并且是开始的好地方。

添加教程

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

改进文档和教程

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

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

参与在线讨论

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

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

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

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

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

审查未解决的拉取请求

我们感谢您帮助审查和评论拉取请求。我们的团队致力于将未解决的拉取请求数量保持在可管理的规模，如果我们需要更多信息，我们会快速响应，并且我们会合并我们认为有用的 PR。但是，由于高度关注，始终欢迎更多人关注拉取请求。

提高代码可读性

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

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

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

推广 PyTorch

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

问题分类

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

关于开源开发

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

• 没有“声明”问题的方法。 人们在决定处理某个问题时，通常希望“声明”该问题，以确保在其他人最终处理该问题时不会浪费工作。这在开源中效果不佳，因为有人可能会决定处理某些事情，但最终没有时间去做。请随意以咨询方式提供信息，但归根结底，我们将采用正在运行的代码和大致共识来快速前进。

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

要避免的常见错误

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

  • 我们要求进行测试的原因有几个

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

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

  • 什么时候可以不添加测试？有时更改可能不方便测试，或者更改显然是正确的（并且不太可能被破坏），因此可以不测试它。相反，如果更改似乎可能（或已知可能）被意外破坏，那么花时间制定测试策略就很重要。

• 您的 PR 是否太长？

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

  • 什么时候可以提交大的 PR？如果在问题中进行了相应的设计讨论，并由将要审查您的差异的人员签字，那将会有很大帮助。我们还可以帮助提供有关如何将大型更改拆分为可单独交付的部分的建议。同样，如果对 PR 的内容有完整的描述，那将会有所帮助：如果我们知道里面的内容，审查代码会更容易！

• 对细微之处进行注释？ 如果您的代码的行为很细致，请添加额外的注释和文档，以便我们更好地理解您的代码意图。

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

• 您是否要接触非常核心的组件？ 为了防止重大回归，接触核心组件的拉取请求会受到额外的审查。在进行重大更改之前，请确保您已与团队讨论过您的更改。

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

• 您是否接触了与 PR 无关的代码？ 为了帮助代码审查，请仅在您的拉取请求中包含与您的更改直接相关的文件。

常见问题解答

• 我如何以审查者的身份做出贡献？ 如果社区开发者重现问题、试用新功能或以其他方式帮助我们识别或排除问题，则会非常有价值。在任务或拉取请求上评论您的环境详细信息非常有帮助，并且我们对此表示感谢。

• CI 测试失败，这意味着什么？ 可能是您的 PR 基于损坏的主分支？您可以尝试在最新的主分支之上重新调整您的更改。您还可以在 https://hud.pytorch.org/ 查看主分支 CI 的当前状态。

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

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

关于文档

Python 文档

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

• 站点：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 页面提供服务。

• 站点：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 源文件或 restructured-text (rst) 文件构建。

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

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

教程构建概述

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

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

贡献新教程

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