注意

此页面已弃用。请参阅 PyTorch 维基百科上的贡献指南。

PyTorch 贡献指南 ¶

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

贡献流程 ¶

PyTorch 组织由 PyTorch 治理和贡献指南，可在 CONTRIBUTING.md 中找到。

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

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

• 搞清楚你要做什么。大多数开源贡献都来自那些在挠自己痒痒的人。然而，如果你不知道你想做什么，或者只是想更多地了解这个项目，以下是一些寻找合适任务的技巧：

  • 查看问题跟踪器，看看是否有你知道如何解决的问题。其他贡献者确认过的问题通常更容易调查。我们还维护了一些标签，用于标记可能适合新人的问题，例如“入门”和“1 小时”，尽管这些标签的维护并不那么好。

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

• 确定你更改的范围，并在 GitHub 问题中寻求设计评论，如果更改较大。大多数拉取请求都很小；在这种情况下，无需告诉我们你想要做什么，只需开始做。但如果更改较大，通常在提交 RFC 之前先获取一些设计评论是个好主意。

  • 如果您不知道将要发生多大的变化，我们可以帮助您弄清楚！只需在问题或开发讨论中发布相关信息即可。

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

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

  • 核心更改和重构可能相当难以协调，因为 PyTorch 主分支的开发速度相当快。对于基本或跨领域的更改，请务必提出建议；我们通常可以提供有关如何将这些更改分阶段进行以便更容易审查的指导。

• 编写代码！

  • 请参阅 CONTRIBUTING.md 文件，获取使用 PyTorch 的技术性工作建议。

• 提交一个 pull request。

  • 如果您还没有准备好让 pull request 被审查，请先创建一个草稿 pull request - 您可以在稍后通过点击“Ready for review”按钮将其转换为完整的 PR。您也可以在草稿状态下在 PR 标题前加上[WIP]（“工作进行中”）。在审查过程中，我们将忽略草稿 PR。如果您正在处理一个复杂的变化，从草稿开始是个好主意，因为您需要花时间查看 CI 结果，以查看是否一切顺利。

  • 找到适合您更改的审稿人。我们有一些人经常浏览 PR 队列并尝试审查所有内容，但如果您知道受您补丁影响的子系统维护者是谁，请直接在 pull request 中包含他们。您可以了解更多关于可能审查您代码的“感兴趣的人”。

• 不断迭代 pull request，直到它被接受！

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

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

入门指南

提出新功能

新功能想法最好在特定的问题上进行讨论。请尽可能提供信息，包括任何伴随的数据，以及您的解决方案。PyTorch 团队和社区经常审查他们认为可以提供帮助的新问题和评论。如果您对自己的解决方案有信心，请直接实施。

报告问题

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

实现功能或修复错误

如果你想修复特定问题，最好在单个问题中评论你的意图。然而，除非我们之前与开发者合作过，否则我们不会锁定或分配问题。就问题展开对话并讨论你的解决方案是最好的。PyTorch 团队可以提供节省你时间的指导。

标记为“first-new-issue”、“低”或“中”优先级的问题提供了最佳的入门点，是开始的好地方。

添加教程

PyTorch.org 上的许多教程都来自社区本身，我们欢迎更多的贡献。想了解更多关于如何贡献新教程的信息，您可以在这里了解：GitHub 上的 PyTorch.org 教程贡献指南

改进文档与教程

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

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

参与在线讨论

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

提交拉取请求以修复开放问题

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

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

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

审查开放拉取请求

我们感谢您审查和评论拉取请求。我们团队努力保持开放拉取请求的数量在可管理的范围内，如果需要，我们会快速回应以获取更多信息，并合并我们认为有用的 PR。然而，由于兴趣水平很高，额外的关注总是受欢迎的。

提高代码可读性 ¶

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

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

欢迎更多的测试覆盖率。

推广 PyTorch

您在项目、研究论文、撰写、博客或互联网上关于 PyTorch 的讨论，有助于提高 PyTorch 和我们日益增长的社区的知名度。请通过 marketing@pytorchorg 联系我们以获取市场支持。

问题分类

如果您认为某个问题可能需要特定的标签或复杂度级别，请在问题下评论并分享您的观点。如果您认为一个问题分类不当，请评论并告知团队。

关于开源开发

如果这是你第一次为开源项目做贡献，开发过程中的某些方面可能对你来说很陌生。

• 没有办法“认领”问题。当人们决定着手处理某个问题时，他们常常想要“认领”该问题，以确保不会有人做了无用功。但在开源项目中，这并不太有效，因为有人可能会决定着手做某事，但最终没有时间去做。请随意提供咨询性信息，但最终，我们将以运行代码和达成共识的方式快速推进。

• 新功能的标准很高。与公司环境不同，在那里编写代码的人隐含地“拥有”它，并且可以预期他们将负责维护代码的整个生命周期，一旦代码合并到开源项目中，它立即成为所有维护者的集体责任。当我们合并代码时，我们，作为维护者，表示我们可以审查后续的更改并对代码进行修复。这自然导致了对贡献的高标准。

常见错误及避免方法

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

  • 我们要求测试有几个原因：

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

    2. 首先，这有助于我们判断补丁是否正确（是的，我们已经审查过了，但正如 Knuth 所说，“小心下面的代码，因为我没有运行它，只是证明了它是正确的”）

  • 在什么情况下可以不添加测试？有时一个更改不方便进行测试，或者更改显然是正确的（并且不太可能出错），那么不进行测试是可以的。相反，如果一个更改似乎很可能会意外出错（或者已知很可能会出错），那么投入时间制定测试策略是很重要的。

• 你的 PR（Pull Request）太长了吗？

  • 对于我们来说，审查和合并小的 PR（Pull Request）更容易。审查 PR 的难度与其大小呈非线性关系。

  • 提交大型的 PR 何时合适？如果有一个相应的 issue 设计讨论，并且得到了将要审查你的 diff 的人的签字，那就很有帮助。我们还可以提供关于如何将大型更改拆分为可独立发布的部分的建议。同样，如果 PR 的内容有完整的描述，那就很有帮助：如果我们知道里面有什么，那么审查代码就更容易了！

• 对于微妙的事情有什么评论吗？在代码行为复杂的情况下，请包括额外的注释和文档，以便我们更好地理解代码的意图。

• 你添加了 hack 吗？有时候，正确的答案就是 hack。但通常，我们得讨论一下。

• 你想修改非常核心的组件吗？为了防止重大回归，修改核心组件的 pull request 会受到额外的审查。在进行重大更改之前，请确保你已经与团队讨论了你的更改。

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

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

常见问题

• 我如何作为审阅者进行贡献？如果社区开发者能够重现问题、尝试新功能或帮助我们识别或调试问题，那么这将非常有价值。在任务或 pull request 上评论您的环境详细信息是有帮助且受欢迎的。

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

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

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

在文档部分

Python 文档部分

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

• 网站：https://pytorch.org/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.org/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.org/tutorials

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

深度翻译教程概述 ¶

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

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

贡献新教程 ¶

查看 PyTorch.org 教程贡献指南。