PyTorch 貢獻(xiàn)指南

原文：PyTorch 貢獻(xiàn)指南

PyTorch 是 GPU 加速的 Python 張量計(jì)算軟件包，用于構(gòu)建基于基于磁帶的 autograd 系統(tǒng)構(gòu)建的深度神經(jīng)網(wǎng)絡(luò)。

PyTorch 貢獻(xiàn)過(guò)程

PyTorch 組織受 PyTorch 治理管轄。

PyTorch 開(kāi)發(fā)過(guò)程涉及核心開(kāi)發(fā)團(tuán)隊(duì)和社區(qū)之間的大量公開(kāi)討論。

PyTorch 的運(yùn)行與 GitHub 上的大多數(shù)開(kāi)源項(xiàng)目相似。 但是，如果您以前從未為開(kāi)源項(xiàng)目做過(guò)貢獻(xiàn)，那么這是基本過(guò)程。

• 弄清楚您要做什么。 大多數(shù)開(kāi)源貢獻(xiàn)來(lái)自于人們撓癢癢的人。 但是，如果您不知道要從事什么工作，或者只是想進(jìn)一步了解該項(xiàng)目，請(qǐng)參考以下提示，以查找合適的任務(wù)：
  • 瀏覽問(wèn)題跟蹤器，看看是否有任何已知的解決方法。 由其他貢獻(xiàn)者確認(rèn)的問(wèn)題往往更易于調(diào)查。 我們還維護(hù)了一些可能對(duì)新人有益的標(biāo)簽，例如訓(xùn)練營(yíng)和 1 小時(shí)，盡管這些標(biāo)簽維護(hù)得不太好。
  • 加入我們的 Slack，讓我們知道您有興趣了解 PyTorch。 我們非常樂(lè)意幫助研究人員和合作伙伴加快使用代碼庫(kù)的速度。
• 找出更改的范圍，并就 GitHub 問(wèn)題(如果涉及的范圍太大）尋求設(shè)計(jì)意見(jiàn)。 大多數(shù)拉取請(qǐng)求很?。?在這種情況下，無(wú)需讓我們知道您想做什么，只需破解即可。 但是，如果變化很大，通常最好先獲得一些設(shè)計(jì)意見(jiàn)。
  • 如果您不知道更改會(huì)有多大，我們可以幫助您解決！ 只需發(fā)布有關(guān)問(wèn)題或松弛的信息即可。
  • 一些功能的添加非常標(biāo)準(zhǔn)化。 例如，許多人向 PyTorch 添加新的運(yùn)算符或優(yōu)化器。 在這些情況下，設(shè)計(jì)討論主要?dú)w結(jié)為“我們是否需要此運(yùn)算符/優(yōu)化器？” 給出其實(shí)用性的證據(jù)，例如，在同行評(píng)審論文中的用法或在其他框架中的存在，在提出這種情況時(shí)會(huì)有所幫助。
  • 通常不接受從最近發(fā)布的研究中添加運(yùn)算符/算法，除非有大量證據(jù)表明這項(xiàng)新發(fā)表的研究成果具有開(kāi)創(chuàng)性，并將最終成為該領(lǐng)域的標(biāo)準(zhǔn)。 如果不確定方法的用途，請(qǐng)?jiān)趯?shí)施 PR 之前先打開(kāi)問(wèn)題。
  • 核心變更和重構(gòu)可能很難協(xié)調(diào)，因?yàn)?PyTorch master 的開(kāi)發(fā)速度非常快。 絕對(duì)接觸基本的或跨領(lǐng)域的變化； 我們通?？梢蕴峁┯嘘P(guān)如何將這些更改分成更容易檢查的片段的指導(dǎo)。
• 編碼！
  • 有關(guān)以技術(shù)形式使用 PyTorch 的建議，請(qǐng)參閱技術(shù)指南。
• 打開(kāi)拉取請(qǐng)求。
  • 如果您還沒(méi)有準(zhǔn)備好審查請(qǐng)求請(qǐng)求，請(qǐng)用[WIP]標(biāo)記它。 審核通過(guò)時(shí)，我們將忽略它。 如果您要進(jìn)行復(fù)雜的更改，最好先將其作為 WIP 進(jìn)行，因?yàn)槟鷮⑿枰ㄙM(fèi)一些時(shí)間查看 CI 的結(jié)果以查看是否可行。
  • 為您的更改找到合適的審閱者。 我們有一些人定期檢查 PR 隊(duì)列并嘗試檢查所有內(nèi)容，但是如果您碰巧知道受補(bǔ)丁影響的給定子系統(tǒng)的維護(hù)者是誰(shuí)，請(qǐng)隨時(shí)將他們直接包含在請(qǐng)求請(qǐng)求中。 您可以在 PyTorch 子系統(tǒng)所有權(quán)上了解有關(guān)此結(jié)構(gòu)的更多信息。
• 迭代拉取請(qǐng)求，直到接受為止！
  • 我們將盡最大努力減少審閱往返次數(shù)，并僅在出現(xiàn)重大問(wèn)題時(shí)才阻止 PR。
  • 一旦請(qǐng)求請(qǐng)求被接受并且 CI 已通過(guò)，則您無(wú)需執(zhí)行其他任何操作。 我們將為您合并 PR。

入門

提出新功能

最好在特定問(wèn)題上討論新功能的想法。 請(qǐng)?zhí)峁┍M可能多的信息，所有隨附數(shù)據(jù)以及建議的解決方案。 PyTorch 團(tuán)隊(duì)和社區(qū)經(jīng)常在他們認(rèn)為有幫助的地方審查新問(wèn)題和評(píng)論。 如果您對(duì)解決方案充滿信心，請(qǐng)繼續(xù)實(shí)施它。

報(bào)告問(wèn)題

如果您發(fā)現(xiàn)了問(wèn)題，請(qǐng)首先在存儲(chǔ)庫(kù)中搜索現(xiàn)有問(wèn)題列表。 如果找不到類似的問(wèn)題，請(qǐng)創(chuàng)建一個(gè)新的問(wèn)題。 提供盡可能多的信息來(lái)重現(xiàn)有問(wèn)題的行為。 此外，包括其他任何見(jiàn)解，例如您期望的行為。

實(shí)施功能或修復(fù)錯(cuò)誤

如果您想解決特定的問(wèn)題，最好有針對(duì)性地對(duì)單個(gè)問(wèn)題發(fā)表評(píng)論。 但是，除非我們之前曾與開(kāi)發(fā)人員合作，否則我們不會(huì)鎖定或分配問(wèn)題。 最好就此問(wèn)題進(jìn)行對(duì)話并討論您建議的解決方案。 PyTorch 團(tuán)隊(duì)可以提供指導(dǎo)，以節(jié)省您的時(shí)間。

標(biāo)為“新發(fā)行”，“低”或“中”優(yōu)先級(jí)的問(wèn)題是最好的切入點(diǎn)，是一個(gè)很好的起點(diǎn)。

添加教程

pytorch.org 上的大量教程都來(lái)自社區(qū)本身，我們歡迎您提供其他幫助。 要了解有關(guān)如何撰寫(xiě)新教程的更多信息，您可以在此處了解更多信息： Github 上的 PyTorch.org 教程貢獻(xiàn)指南

改進(jìn)文檔&教程

我們旨在制作高質(zhì)量的文檔和教程。 在極少數(shù)情況下，內(nèi)容包括錯(cuò)別字或錯(cuò)誤。 如果您發(fā)現(xiàn)可以解決的問(wèn)題，請(qǐng)向我們發(fā)送請(qǐng)求以供考慮。

請(qǐng)查看文檔部分，以了解我們的系統(tǒng)如何工作。

參加在線討論

您可以在 PyTorch 討論論壇上找到活躍的討論。

提交拉取請(qǐng)求以解決未解決的問(wèn)題

您可以在此處查看所有未解決問(wèn)題的列表。 對(duì)問(wèn)題發(fā)表評(píng)論是引起團(tuán)隊(duì)關(guān)注的好方法。 在這里，您可以分享您的想法以及如何解決該問(wèn)題。

對(duì)于更具挑戰(zhàn)性的問(wèn)題，團(tuán)隊(duì)將為如何最好地解決問(wèn)題提供反饋和指導(dǎo)。

如果您無(wú)法自行解決問(wèn)題，請(qǐng)?jiān)u論并分享您是否可以重現(xiàn)該問(wèn)題對(duì)于幫助團(tuán)隊(duì)確定問(wèn)題區(qū)域很有用。

審查未完成的拉取請(qǐng)求

感謝您為審核請(qǐng)求提出評(píng)論的意見(jiàn)。 我們的團(tuán)隊(duì)努力將公開(kāi)請(qǐng)求的數(shù)量保持在可管理的范圍內(nèi)，我們會(huì)在需要時(shí)迅速做出回應(yīng)以提供更多信息，并且我們合并認(rèn)為有用的 PR。 但是，由于人們的關(guān)注度很高，因此請(qǐng)多加關(guān)注拉取請(qǐng)求。

提高代碼可讀性

提高代碼的可讀性可以幫助所有人。 通常，提交少量觸摸少量文件的請(qǐng)求，而不是提交大量觸摸許多文件的請(qǐng)求。 在 PyTorch 論壇此處或與您的改進(jìn)相關(guān)的問(wèn)題上開(kāi)始討論是最好的入門方法。

添加測(cè)試用例以使代碼庫(kù)更健壯

附加測(cè)試覆蓋范圍表示贊賞。

推廣 PyTorch

在項(xiàng)目，研究論文，文章，博客或互聯(lián)網(wǎng)上的一般性討論中使用 PyTorch 有助于提高對(duì) PyTorch 和我們不斷發(fā)展的社區(qū)的認(rèn)識(shí)。

分類問(wèn)題

如果您認(rèn)為某個(gè)問(wèn)題可以從特定的標(biāo)記或復(fù)雜性級(jí)別中受益，請(qǐng)對(duì)該問(wèn)題發(fā)表評(píng)論并分享您的觀點(diǎn)。 如果您認(rèn)為問(wèn)題未正確歸類，請(qǐng)發(fā)表評(píng)論并告知團(tuán)隊(duì)。

關(guān)于開(kāi)源開(kāi)發(fā)

如果這是您第一次為開(kāi)放源代碼項(xiàng)目做貢獻(xiàn)，那么開(kāi)發(fā)過(guò)程的某些方面對(duì)您來(lái)說(shuō)似乎并不尋常。

• 無(wú)法“聲明”問(wèn)題。 人們通常希望在決定處理某個(gè)問(wèn)題時(shí)“主張”該問(wèn)題，以確保在其他人最終處理該問(wèn)題時(shí)不會(huì)浪費(fèi)工作。 在開(kāi)放源代碼中，這實(shí)際上并不是很好，因?yàn)橛腥丝赡軙?huì)決定從事某項(xiàng)工作，最終沒(méi)有時(shí)間去做。 隨時(shí)以咨詢的方式提供信息，但最終，我們將獲得運(yùn)行代碼和粗略的共識(shí)。
• 添加了新功能的較高標(biāo)準(zhǔn)。 與公司環(huán)境不同，在公司環(huán)境中，編寫(xiě)代碼的人隱式“擁有”該代碼，并且可以期望在代碼生命周期的開(kāi)始就對(duì)其進(jìn)行處理，一旦將合并請(qǐng)求合并到一個(gè)開(kāi)源項(xiàng)目中，它就會(huì)立即 成為項(xiàng)目所有維護(hù)者的集體責(zé)任。 當(dāng)我們合并代碼時(shí)，我們是在說(shuō)維護(hù)者能夠查看隨后的更改并對(duì)代碼進(jìn)行錯(cuò)誤修正。 這自然會(huì)導(dǎo)致更高的貢獻(xiàn)標(biāo)準(zhǔn)。

避免的常見(jiàn)錯(cuò)誤

• 您是否添加了測(cè)試？ (或者如果很難測(cè)試更改，您是否描述了如何測(cè)試更改？）
  • 對(duì)于為什么要進(jìn)行測(cè)試，我們有一些動(dòng)機(jī)：
    1. 來(lái)告訴我們以后是否要打破
    2. 幫助我們首先確定補(bǔ)丁程序是否正確(是的，我們確實(shí)對(duì)其進(jìn)行了審核，但是正如 Knuth 所說(shuō)，“請(qǐng)注意以下代碼，因?yàn)槲覜](méi)有運(yùn)行它，只是證明它是正確的”）
  • 什么時(shí)候可以不添加測(cè)試？ 有時(shí)，更改無(wú)法方便地進(jìn)行測(cè)試，或者更改顯然很正確(并且不太可能被破壞），因此可以不進(jìn)行測(cè)試。 相反，如果更改似乎有可能(或已知有可能）被意外破壞，那么花時(shí)間制定測(cè)試策略就很重要。
• 您的公關(guān)時(shí)間過(guò)長(zhǎng)嗎？
  • 對(duì)我們來(lái)說(shuō)，審查和合并小型 PR 更加容易。 審查 PR 的難度與其規(guī)模成非線性關(guān)系。
  • 什么時(shí)候可以提交大公關(guān)？ 如果在一個(gè)問(wèn)題中進(jìn)行了相應(yīng)的設(shè)計(jì)討論，并從將要檢查您的差異的人員處簽名，則很有幫助。 我們還可以幫助您提供建議，說(shuō)明如何將較大的更改分成可單獨(dú)裝運(yùn)的部分。 同樣，如果對(duì) PR 的內(nèi)容有完整的描述，也會(huì)有所幫助：如果我們知道其中的內(nèi)容，則更容易查看代碼！
• 對(duì)微妙的事物發(fā)表評(píng)論嗎？ 如果您的代碼行為有細(xì)微差別，請(qǐng)?zhí)峁╊~外的注釋和文檔，以使我們更好地了解您的代碼的意圖。
• 您添加了 hack 嗎？ 有時(shí)候，破解是正確的答案。 但是通常我們將不得不討論它。
• 您想觸摸一個(gè)非常核心的組件嗎？ 為了防止出現(xiàn)重大衰退，涉及核心組件的拉取請(qǐng)求會(huì)受到額外的審查。 在進(jìn)行重大更改之前，請(qǐng)確保您已與團(tuán)隊(duì)討論過(guò)更改。
• 是否要添加新功能？ 如果要添加新功能，請(qǐng)對(duì)相關(guān)問(wèn)題發(fā)表評(píng)論。 我們的團(tuán)隊(duì)嘗試發(fā)表評(píng)論并向社區(qū)提供反饋。 在開(kāi)發(fā)新功能之前，最好與團(tuán)隊(duì)和社區(qū)的其他成員進(jìn)行公開(kāi)討論。 這可以幫助我們隨時(shí)了解您的工作，并增加合并的可能性。
• 您是否觸摸了與 PR 無(wú)關(guān)的代碼？ 為幫助進(jìn)行代碼審查，請(qǐng)僅在請(qǐng)求請(qǐng)求中包括與您的更改直接相關(guān)的文件。

經(jīng)常問(wèn)的問(wèn)題

• 我如何才能擔(dān)任審稿人？ 如果社區(qū)開(kāi)發(fā)人員重現(xiàn)問(wèn)題，嘗試新功能或以其他方式幫助我們確定問(wèn)題或?qū)ζ溥M(jìn)行故障排除，則將具有很多價(jià)值。 使用您的環(huán)境詳細(xì)信息對(duì)任務(wù)進(jìn)行注釋或請(qǐng)求將很有幫助并受到贊賞。
• CI 測(cè)試失敗，這是什么意思？ 也許您需要與 master 合并或以最新更改為基礎(chǔ)。 推送更改應(yīng)重新觸發(fā) CI 測(cè)試。 如果測(cè)試持續(xù)進(jìn)行，您將需要查找錯(cuò)誤消息并解決相關(guān)問(wèn)題。
• 最高風(fēng)險(xiǎn)的更改是什么？ 涉及構(gòu)建配置的任何內(nèi)容都是有風(fēng)險(xiǎn)的領(lǐng)域。 除非事先與團(tuán)隊(duì)討論，否則請(qǐng)避免更改這些內(nèi)容。
• 嘿，我的分支上出現(xiàn)了一個(gè)提交，這是怎么回事？ 有時(shí)，另一個(gè)社區(qū)成員會(huì)為您的請(qǐng)求請(qǐng)求或分支提供補(bǔ)丁或修復(fù)。 為了使 CI 測(cè)試通過(guò)，通常需要這樣做。

關(guān)于文檔

Python 文檔

PyTorch 文檔是使用 Sphinx 從 python 源生成的。 生成的 HTML 復(fù)制到 pytorch.github.io 的 master 分支中的 docs 文件夾中，并通過(guò) GitHub 頁(yè)面提供。

• 網(wǎng)站： http://pytorch.org/docs
• GitHub： https://github.com/pytorch/pytorch/tree/master/docs
• 從以下服務(wù)器提供： https://github.com/pytorch/pytorch.github.io/tree/master/doc

C ++文件

對(duì)于 C ++代碼，我們使用 Doxygen 生成內(nèi)容文件。 C ++文檔建立在特殊的服務(wù)器上，并將生成的文件復(fù)制到 https://github.com/pytorch/cppdocs 存儲(chǔ)庫(kù)，并從 GitHub 頁(yè)面提供。

• 網(wǎng)站： http://pytorch.org/cppdocs
• GitHub： https://github.com/pytorch/pytorch/tree/master/docs/cpp
• 從以下服務(wù)器提供： https://github.com/pytorch/cppdocs

講解

PyTorch 教程是用于幫助理解使用 PyTorch 完成特定任務(wù)或了解更全面概念的文檔。 教程是使用 Sphinx-Gallery 從可執(zhí)行的 python 源文件或重組文本(rst）文件構(gòu)建的。

• 網(wǎng)站： http://pytorch.org/tutorials
• GitHub： http://github.com/pytorch/tutorials

教程構(gòu)建概述

對(duì)于教程，拉取請(qǐng)求使用 CircleCI 觸發(fā)重建整個(gè)站點(diǎn)，以測(cè)試更改的效果。 該建筑被分割為 9 個(gè)工人建筑，總共耗時(shí)約 40 分鐘。 同時(shí)，我們使用 make html-noplot 進(jìn)行 Netlify 構(gòu)建，該構(gòu)建無(wú)需將筆記本輸出呈現(xiàn)為頁(yè)面即可快速瀏覽的站點(diǎn)。

接受 PR 后，可從 CircleCI 重建和部署站點(diǎn)。

撰寫(xiě)新教程

PyTorch.org 教程貢獻(xiàn)指南