注意
此页面已弃用。请参阅 PyTorch Wiki 上的贡献指南。
PyTorch 贡献指南¶
PyTorch 是一个 GPU 加速的 Python 张量计算软件包,使用基于磁带的自动微分系统构建深度神经网络。
贡献流程¶
PyTorch 组织由PyTorch 治理管理,技术贡献指南可在CONTRIBUTING.md中找到。
PyTorch 开发过程包含核心开发团队和社区之间大量开放讨论。
PyTorch 的运作方式与 GitHub 上的大多数开源项目相似。但是,如果您以前从未为开源项目做过贡献,这里是基本流程。
找出您要开展的工作。 大多数开源贡献来自人们解决自己的痛点。但是,如果您不知道自己想做什么,或者只是想更熟悉该项目,以下是一些寻找合适任务的建议
确定您变更的范围,如果是大型变更,请在 GitHub issue 上寻求设计评论。 大多数拉取请求都很小;在这种情况下,无需让我们知道您想做什么,直接开始即可。但如果变更很大,通常最好先通过提交 RFC获取一些设计评论。
一些功能添加非常标准化;例如,很多人向 PyTorch 添加新的操作符或优化器。这些情况下的设计讨论主要归结为“我们是否需要此操作符/优化器?” 提供其有用性的证据,例如在同行评审论文中的使用或在其他框架中的存在,对于支持此论点有所帮助。
通常不接受添加来自最新研究的操作符/算法,除非有压倒性证据表明这项新发表的工作具有开创性成果,并且最终将成为该领域的标准。如果您不确定您的方法属于哪种情况,请在实现 PR 之前先开一个 issue。
核心变更和重构可能很难协调,因为 PyTorch 主分支的开发速度很快。对于基础性或跨领域的变更,请务必联系我们;我们通常可以提供有关如何将此类变更分阶段为更易于评审的块的指导。
编写代码!
有关技术形式的 PyTorch 工作建议,请参阅CONTRIBUTING.md文件。
打开拉取请求。
如果您尚未准备好进行拉取请求评审,请先创建草稿拉取请求 - 之后可以通过按“Ready for review”(准备好评审)按钮将其转换为完整 PR。您也可以在 PR 标题前添加“[WIP]”(工作进行中),以便其仍处于草稿状态。我们将在评审过程中忽略草稿 PR。如果您正在处理复杂变更,最好先从草稿开始,因为您需要花时间查看 CI 结果以了解情况是否顺利。
为您的变更找到合适的评审者。我们有一些人定期检查 PR 队列并尝试评审所有内容,但如果您恰好知道受您补丁影响的给定子系统的维护者是谁,请随时将其直接包含在拉取请求中。您可以从关注人士中了解更多可能评审您代码的人。
迭代拉取请求直到被接受!
我们将尽最大努力减少评审往返次数,并且只在存在重大问题时阻止 PR。对于拉取请求中最常见的问题,请查看常见错误。
一旦拉取请求被接受且 CI 通过,您无需再做任何事情;我们将为您合并 PR。
入门¶
提出新功能¶
新功能想法最好在特定 issue 上讨论。请尽可能多地包含信息、任何随附数据以及您提出的解决方案。PyTorch 团队和社区经常评审新的 issue 和评论,并在认为能提供帮助时进行回复。如果您对自己的解决方案充满信心,请直接实现。
实现功能或修复错误¶
如果您想修复特定问题,最好在该问题下方评论说明您的意图。但是,除了与开发者合作过的情况外,我们不会锁定或分配问题。最好在 issue 上展开对话,讨论您提出的解决方案。PyTorch 团队可以提供指导,从而节省您的时间。
标记为 first-new-issue、low 或 medium priority 的问题是最佳的切入点,非常适合入门。
添加教程¶
pytorch.org 上的许多教程都来自社区本身,我们欢迎额外贡献。要了解如何贡献新教程,您可以在这里了解更多信息:GitHub 上的 PyTorch.org 教程贡献指南
参与在线讨论¶
您可以在用户使用的PyTorch 讨论论坛以及开发者和维护者使用的PyTorch 开发者讨论论坛上找到活跃的讨论。
提交拉取请求以修复开放问题¶
您可以在此处查看所有开放问题的列表。评论问题是引起团队注意的好方法。您可以在此处分享您的想法以及您计划如何解决问题。
对于更具挑战性的问题,团队将提供反馈和指导,说明如何最好地解决问题。
如果您自己无法解决问题,评论并分享您是否可以重现问题可以帮助团队识别问题区域。
评审开放的拉取请求¶
我们感谢您帮助评审和评论拉取请求。我们的团队努力将开放拉取请求的数量保持在可管理的范围内,如果需要更多信息,我们会快速响应,我们会合并我们认为有用的 PR。但是,由于高水平的关注,我们总是欢迎更多人评审拉取请求。
提高代码可读性¶
提高代码可读性对每个人都有益。提交少量更改少数文件的拉取请求通常比提交大量更改许多文件的拉取请求更好。在 PyTorch 论坛 此处 或与您的改进相关的 issue 上发起讨论是最好的入门方式。
添加测试用例以使代码库更健壮¶
我们感谢额外的测试覆盖。
推广 PyTorch¶
您在您的项目、研究论文、文章、博客或互联网上的日常讨论中使用 PyTorch 有助于提高人们对 PyTorch 和我们不断壮大的社区的认识。请通过 marketing@pytorch.org 联系我们以获得市场支持。
问题分类¶
如果您认为某个问题可以受益于特定的标签或复杂度级别,请在该问题下评论并分享您的看法。如果您认为某个问题分类不当,请评论并告知团队。
关于开源开发¶
如果这是您第一次为开源项目做贡献,开发过程的某些方面可能对您来说不寻常。
没有办法“认领”问题。 人们通常希望在决定处理问题时“认领”它,以确保在其他人最终处理同一问题时不会浪费工作。这在开源中不太有效,因为某人可能决定处理某事,但最终没有时间。您可以随意提供建议信息,但最终,我们将接受可运行的代码和大致共识以快速向前推进。
新功能有很高的门槛。 与企业环境不同,在企业环境中,编写代码的人隐式地“拥有”它,并且在代码的生命周期内可以期望他们负责维护它,一旦拉取请求合并到开源项目中,它立即成为项目所有维护者的集体责任。当我们合并代码时,我们是说我们,维护者,可以评审后续更改并对代码进行错误修复。这自然导致更高的贡献标准。
常见错误¶
您是否添加了测试?(或者如果变更难以测试,您是否描述了如何测试您的变更?)
我们要求添加测试有几个原因
帮助我们判断以后是否会破坏它
帮助我们判断补丁本身是否正确(是的,我们评审了它,但正如 Knuth 所说,“谨防以下代码,因为我没有运行它,只是证明了它的正确性”)
什么时候可以不添加测试?有时,变更无法方便地进行测试,或者变更非常明显正确(并且不太可能被破坏),因此可以不进行测试。相反,如果变更似乎可能(或已知可能)被意外破坏,花时间制定测试策略就很重要。
您的 PR 是否太长?
对于我们来说,评审和合并小型 PR 更容易。评审 PR 的难度与其大小呈非线性关系。
什么时候可以提交大型 PR?如果在 issue 中有相应的设计讨论,并得到了将评审您差异的人的签字同意,这会很有帮助。我们还可以提供有关如何将大型变更分解为可单独交付的部分的建议。同样,如果 PR 内容有完整描述,这也有帮助:如果我们知道代码内部是什么,评审代码会更容易!
对微妙之处的评论? 如果您的代码行为微妙,请包含额外的评论和文档,以便我们更好地理解您的代码意图。
您是否添加了临时解决方案? 有时,正确的答案是临时解决方案。但通常,我们需要讨论它。
您想触及核心组件吗? 为了防止重大回归,触及核心组件的拉取请求会受到额外审查。在进行重大更改之前,请确保您已与团队讨论过您的更改。
想添加新功能吗? 如果您想添加新功能,请在相关 issue 上评论您的意图。我们的团队会尝试评论并向社区提供反馈。在构建新功能之前,最好与团队和社区其他成员进行公开讨论。这有助于我们了解您正在开展的工作,并增加其合并的机会。
您是否更改了与 PR 无关的代码? 为了方便代码评审,请仅在您的拉取请求中包含与您的更改直接相关的文件。
常见问题解答¶
我如何作为评审者做贡献? 如果社区开发者重现问题、尝试新功能或以其他方式帮助我们识别或排除问题,这非常有价值。在任务或拉取请求上评论并提供您的环境详细信息非常有用且受到赞赏。
CI 测试失败了,是什么意思? 也许您的 PR 基于一个损坏的主分支?您可以尝试在最新的主分支之上 rebase 您的更改。您也可以在https://hud.pytorch.org/查看主分支 CI 的当前状态。
哪些是最高风险的更改? 任何涉及构建配置的区域都是高风险区域。除非您事先与团队讨论过,否则请避免更改这些内容。
嘿,我的分支上出现了一个提交,这是怎么回事? 有时,其他社区成员会为您的拉取请求或分支提供补丁或修复。这通常是为了使 CI 测试通过所必需的。
关于文档¶
Python 文档¶
PyTorch 文档由 Python 源代码使用 Sphinx 生成。生成的 HTML 会复制到 pytorch.github.io 主分支的 docs 文件夹中,并通过 GitHub Pages 提供服务。
C++ 文档¶
对于 C++ 代码,我们使用 Doxygen 生成内容文件。C++ 文档在专用服务器上构建,生成的 文件复制到https://github.com/pytorch/cppdocs 仓库,并通过 GitHub Pages 提供服务。
教程¶
PyTorch 教程是用于帮助理解如何使用 PyTorch 完成特定任务或理解更全面的概念的文档。教程使用 Sphinx-Gallery 从可执行的 Python 源代码文件或 restructured-text (rst) 文件构建。
教程构建概览¶
对于教程,拉取请求会触发使用 CircleCI 重新构建整个站点,以测试更改的效果。此构建被分片到 9 个工作进程构建中,总共需要约 40 分钟。同时,我们使用 make html-noplot 进行 Netlify 构建,它在不渲染笔记本输出到页面的情况下构建站点,以便快速评审。
PR 接受后,站点将使用 GitHub Actions 重新构建和部署。