PyTorch 贡献指南

原文：PyTorch 贡献指南

PyTorch 是 GPU 加速的 Python 张量计算软件包，用于构建基于基于磁带的 autograd 系统构建的深度神经网络。

PyTorch 贡献过程

PyTorch 组织受 PyTorch 治理管辖。

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

PyTorch 的运行与 GitHub 上的大多数开源项目相似。 但是，如果您以前从未为开源项目做过贡献，那么这是基本过程。

• 弄清楚您要做什么。 大多数开源贡献来自于人们挠痒痒的人。 但是，如果您不知道要从事什么工作，或者只是想进一步了解该项目，请参考以下提示，以查找合适的任务：
  • 浏览问题跟踪器，看看是否有任何已知的解决方法。 由其他贡献者确认的问题往往更易于调查。 我们还维护了一些可能对新人有益的标签，例如训练营和 1 小时，尽管这些标签维护得不太好。
  • 加入我们的 Slack，让我们知道您有兴趣了解 PyTorch。 我们非常乐意帮助研究人员和合作伙伴加快使用代码库的速度。
• 找出更改的范围，并就 GitHub 问题(如果涉及的范围太大）寻求设计意见。 大多数拉取请求很小； 在这种情况下，无需让我们知道您想做什么，只需破解即可。 但是，如果变化很大，通常最好先获得一些设计意见。
  • 如果您不知道更改会有多大，我们可以帮助您解决！ 只需发布有关问题或松弛的信息即可。
  • 一些功能的添加非常标准化。 例如，许多人向 PyTorch 添加新的运算符或优化器。 在这些情况下，设计讨论主要归结为“我们是否需要此运算符/优化器？” 给出其实用性的证据，例如，在同行评审论文中的用法或在其他框架中的存在，在提出这种情况时会有所帮助。
  • 通常不接受从最近发布的研究中添加运算符/算法，除非有大量证据表明这项新发表的研究成果具有开创性，并将最终成为该领域的标准。 如果不确定方法的用途，请在实施 PR 之前先打开问题。
  • 核心变更和重构可能很难协调，因为 PyTorch master 的开发速度非常快。 绝对接触基本的或跨领域的变化； 我们通常可以提供有关如何将这些更改分成更容易检查的片段的指导。
• 编码！
  • 有关以技术形式使用 PyTorch 的建议，请参阅技术指南。
• 打开拉取请求。
  • 如果您还没有准备好审查请求请求，请用[WIP]标记它。 审核通过时，我们将忽略它。 如果您要进行复杂的更改，最好先将其作为 WIP 进行，因为您将需要花费一些时间查看 CI 的结果以查看是否可行。
  • 为您的更改找到合适的审阅者。 我们有一些人定期检查 PR 队列并尝试检查所有内容，但是如果您碰巧知道受补丁影响的给定子系统的维护者是谁，请随时将他们直接包含在请求请求中。 您可以在 PyTorch 子系统所有权上了解有关此结构的更多信息。
• 迭代拉取请求，直到接受为止！
  • 我们将尽最大努力减少审阅往返次数，并仅在出现重大问题时才阻止 PR。
  • 一旦请求请求被接受并且 CI 已通过，则您无需执行其他任何操作。 我们将为您合并 PR。

入门

提出新功能

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

报告问题

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

实施功能或修复错误

如果您想解决特定的问题，最好有针对性地对单个问题发表评论。 但是，除非我们之前曾与开发人员合作，否则我们不会锁定或分配问题。 最好就此问题进行对话并讨论您建议的解决方案。 PyTorch 团队可以提供指导，以节省您的时间。

标为“新发行”，“低”或“中”优先级的问题是最好的切入点，是一个很好的起点。

添加教程

pytorch.org 上的大量教程都来自社区本身，我们欢迎您提供其他帮助。 要了解有关如何撰写新教程的更多信息，您可以在此处了解更多信息： Github 上的 PyTorch.org 教程贡献指南

改进文档&教程

我们旨在制作高质量的文档和教程。 在极少数情况下，内容包括错别字或错误。 如果您发现可以解决的问题，请向我们发送请求以供考虑。

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

参加在线讨论

您可以在 PyTorch 讨论论坛上找到活跃的讨论。

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

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

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

如果您无法自行解决问题，请评论并分享您是否可以重现该问题对于帮助团队确定问题区域很有用。

审查未完成的拉取请求

感谢您为审核请求提出评论的意见。 我们的团队努力将公开请求的数量保持在可管理的范围内，我们会在需要时迅速做出回应以提供更多信息，并且我们合并认为有用的 PR。 但是，由于人们的关注度很高，因此请多加关注拉取请求。

提高代码可读性

提高代码的可读性可以帮助所有人。 通常，提交少量触摸少量文件的请求，而不是提交大量触摸许多文件的请求。 在 PyTorch 论坛此处或与您的改进相关的问题上开始讨论是最好的入门方法。

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

附加测试覆盖范围表示赞赏。

推广 PyTorch

在项目，研究论文，文章，博客或互联网上的一般性讨论中使用 PyTorch 有助于提高对 PyTorch 和我们不断发展的社区的认识。

分类问题

如果您认为某个问题可以从特定的标记或复杂性级别中受益，请对该问题发表评论并分享您的观点。 如果您认为问题未正确归类，请发表评论并告知团队。

关于开源开发

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

• 无法“声明”问题。 人们通常希望在决定处理某个问题时“主张”该问题，以确保在其他人最终处理该问题时不会浪费工作。 在开放源代码中，这实际上并不是很好，因为有人可能会决定从事某项工作，最终没有时间去做。 随时以咨询的方式提供信息，但最终，我们将获得运行代码和粗略的共识。
• 添加了新功能的较高标准。 与公司环境不同，在公司环境中，编写代码的人隐式“拥有”该代码，并且可以期望在代码生命周期的开始就对其进行处理，一旦将合并请求合并到一个开源项目中，它就会立即 成为项目所有维护者的集体责任。 当我们合并代码时，我们是在说维护者能够查看随后的更改并对代码进行错误修正。 这自然会导致更高的贡献标准。

避免的常见错误

• 您是否添加了测试？ (或者如果很难测试更改，您是否描述了如何测试更改？）
  • 对于为什么要进行测试，我们有一些动机：
    1. 来告诉我们以后是否要打破
    2. 帮助我们首先确定补丁程序是否正确(是的，我们确实对其进行了审核，但是正如 Knuth 所说，“请注意以下代码，因为我没有运行它，只是证明它是正确的”）
  • 什么时候可以不添加测试？ 有时，更改无法方便地进行测试，或者更改显然很正确(并且不太可能被破坏），因此可以不进行测试。 相反，如果更改似乎有可能(或已知有可能）被意外破坏，那么花时间制定测试策略就很重要。
• 您的公关时间过长吗？
  • 对我们来说，审查和合并小型 PR 更加容易。 审查 PR 的难度与其规模成非线性关系。
  • 什么时候可以提交大公关？ 如果在一个问题中进行了相应的设计讨论，并从将要检查您的差异的人员处签名，则很有帮助。 我们还可以帮助您提供建议，说明如何将较大的更改分成可单独装运的部分。 同样，如果对 PR 的内容有完整的描述，也会有所帮助：如果我们知道其中的内容，则更容易查看代码！
• 对微妙的事物发表评论吗？ 如果您的代码行为有细微差别，请提供额外的注释和文档，以使我们更好地了解您的代码的意图。
• 您添加了 hack 吗？ 有时候，破解是正确的答案。 但是通常我们将不得不讨论它。
• 您想触摸一个非常核心的组件吗？ 为了防止出现重大衰退，涉及核心组件的拉取请求会受到额外的审查。 在进行重大更改之前，请确保您已与团队讨论过更改。
• 是否要添加新功能？ 如果要添加新功能，请对相关问题发表评论。 我们的团队尝试发表评论并向社区提供反馈。 在开发新功能之前，最好与团队和社区的其他成员进行公开讨论。 这可以帮助我们随时了解您的工作，并增加合并的可能性。
• 您是否触摸了与 PR 无关的代码？ 为帮助进行代码审查，请仅在请求请求中包括与您的更改直接相关的文件。

经常问的问题

• 我如何才能担任审稿人？ 如果社区开发人员重现问题，尝试新功能或以其他方式帮助我们确定问题或对其进行故障排除，则将具有很多价值。 使用您的环境详细信息对任务进行注释或请求将很有帮助并受到赞赏。
• CI 测试失败，这是什么意思？ 也许您需要与 master 合并或以最新更改为基础。 推送更改应重新触发 CI 测试。 如果测试持续进行，您将需要查找错误消息并解决相关问题。
• 最高风险的更改是什么？ 涉及构建配置的任何内容都是有风险的领域。 除非事先与团队讨论，否则请避免更改这些内容。
• 嘿，我的分支上出现了一个提交，这是怎么回事？ 有时，另一个社区成员会为您的请求请求或分支提供补丁或修复。 为了使 CI 测试通过，通常需要这样做。

关于文档

Python 文档

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

• 网站： http://pytorch.org/docs
• GitHub： https://github.com/pytorch/pytorch/tree/master/docs
• 从以下服务器提供： https://github.com/pytorch/pytorch.github.io/tree/master/doc

C ++文件

对于 C ++代码，我们使用 Doxygen 生成内容文件。 C ++文档建立在特殊的服务器上，并将生成的文件复制到 https://github.com/pytorch/cppdocs 存储库，并从 GitHub 页面提供。

• 网站： http://pytorch.org/cppdocs
• GitHub： https://github.com/pytorch/pytorch/tree/master/docs/cpp
• 从以下服务器提供： https://github.com/pytorch/cppdocs

讲解

PyTorch 教程是用于帮助理解使用 PyTorch 完成特定任务或了解更全面概念的文档。 教程是使用 Sphinx-Gallery 从可执行的 python 源文件或重组文本(rst）文件构建的。

• 网站： http://pytorch.org/tutorials
• GitHub： http://github.com/pytorch/tutorials

教程构建概述

对于教程，拉取请求使用 CircleCI 触发重建整个站点，以测试更改的效果。 该建筑被分割为 9 个工人建筑，总共耗时约 40 分钟。 同时，我们使用 make html-noplot 进行 Netlify 构建，该构建无需将笔记本输出呈现为页面即可快速浏览的站点。

接受 PR 后，可从 CircleCI 重建和部署站点。

撰写新教程

PyTorch.org 教程贡献指南