注意

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

PyTorch 贡献指南

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

贡献流程

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

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

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

• **确定您要处理的内容。** 大多数开源贡献来自人们解决自身问题。但是，如果您不知道要处理什么，或者只是想更多地了解该项目，以下是一些查找合适任务的技巧

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

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

• **确定更改的范围，如果更改较大，请在 GitHub 问题上寻求设计意见。** 大多数拉取请求都很小；在这种情况下，无需让我们知道您想做什么，只需开始行动即可。但是，如果更改很大，通常最好先通过 提交 RFC 获取一些设计意见。

  • 如果您不确定更改有多大，我们可以帮助您弄清楚！只需在 问题 或 开发者讨论 上发布相关信息即可。

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

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

  • 核心更改和重构可能难以协调，因为 PyTorch 主分支的开发速度非常快。对于基本更改或跨领域更改，请务必与我们联系；我们通常可以提供有关如何将此类更改分阶段分解为更易于审查的部分的指导。

• 编写代码！

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

• 打开一个拉取请求。

  • 如果您尚未准备好审查拉取请求，请先创建一个草稿拉取请求 - 您可以稍后通过按下“准备审查”按钮将其转换为完整的 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 基于已损坏的主分支？您可以尝试将您的更改重新设置为主分支的最新版本。您还可以查看主分支 CI 的当前状态https://hud.pytorch.org/。

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

• 嘿，我的分支上出现了提交，这是怎么回事？有时，其他社区成员会为您的拉取请求或分支提供补丁或修复。这通常需要才能使 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 源文件或从重组文本 (rst) 文件构建的。

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

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

教程构建概述

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

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

贡献新的教程

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