注意

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

PyTorch 贡献指南

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

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

贡献流程

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

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

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

• 确定您要从事的工作。 大多数开源贡献都来自于解决自己痛点的人。但是，如果您不知道自己想做什么，或者只是想更熟悉该项目，以下是一些有关如何找到合适任务的技巧。

  • 查看 问题跟踪器，看看是否有您知道如何修复的问题。由其他贡献者确认的问题通常更值得研究。我们还维护了一些标签，用于标记适合新人的问题，例如 **bootcamp** 和 **1hr**，尽管这些标签的维护程度较低。

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

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

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

  • 一些功能添加非常标准化；例如，许多人会向 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？如果有一个对应的 issue 设计讨论，并得到将审查您的 diff 的人员的批准，那将大有帮助。我们还可以帮助提供关于如何将大型更改拆分成可单独发布的部分的建议。同样，有一个完整的 PR 内容描述也有帮助：知道里面有什么更容易审查代码！

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

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

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

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

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

常见问题

• 我如何作为审查者贡献？ 社区开发者重现问题、尝试新功能或以其他方式帮助我们识别或解决问题非常有价值。在任务或拉取请求上评论您的环境详细信息很有帮助并且受到赞赏。

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

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

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

关于文档

Python 文档

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

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

• GitHub：pytorch/pytorch

• 提供自：https://pytorch.ac.cn/docs/main

C++ 文档

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

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

• GitHub：pytorch/pytorch

• 提供自：pytorch/cppdocs

教程

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

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

• GitHub：pytorch/tutorials

教程构建概述

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

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

贡献新教程

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