注意
此頁面已過時。請參考 PyTorch Wiki 上的 貢獻指南。
PyTorch 貢獻指南¶
PyTorch 是一個 GPU 加速的 Python Tensor 計算套件，用於使用基於磁帶的 Autograd 系統建構深度神經網路。
貢獻流程¶
PyTorch 組織由 PyTorch 管理 管理，貢獻的技術指南可在 CONTRIBUTING.md 中找到。
PyTorch 開發流程涉及核心開發團隊和社群之間的大量公開討論。
PyTorch 的運作方式與 GitHub 上大多數開源專案類似。但是，如果您以前從未貢獻過開源專案，以下是基本流程。
找出您要處理的內容。 大多數開源貢獻來自於解決自身問題的人。但是，如果您不知道自己想處理什麼，或者只是想更熟悉該專案，以下是一些關於如何找到合適任務的提示
瀏覽 Issue 追蹤器，看看是否有您知道如何修復的問題。 經過其他貢獻者確認的問題往往更值得調查。 我們還為可能適合新手的問題維護了一些標籤，例如 bootcamp 和 1hr，儘管這些標籤的維護程度較差。
歡迎加入我們的 dev discuss，讓我們知道您對了解 PyTorch 感興趣。我們非常樂意協助研究人員和合作夥伴快速上手程式碼庫。
釐清您變更的範圍，如果是大型變更，請在 GitHub issue 上提出設計上的意見。 大部分的 Pull Request 都很小；在這種情況下，不需要讓我們知道您想做什麼，直接開始動手即可。但如果變更範圍很大，最好先 提交 RFC，先取得一些設計上的意見。
如果您不知道變更範圍有多大，我們可以協助您釐清！只要在 issues 或 dev discuss 上發文即可。
有些新增功能非常標準化；例如，很多人都會新增運算子或優化器到 PyTorch。在這些情況下，設計討論主要歸結為：「我們是否需要這個運算子/優化器？」 提供其效用的證據，例如，在同行評審的論文中使用，或存在於其他框架中，對於提出論點有所幫助。
通常不接受從最近發布的研究中新增運算子/演算法，除非有壓倒性的證據表明這項新發布的工作具有突破性的成果，並最終將成為該領域的標準。如果您不確定您的方法屬於哪一種，請先開啟 issue，再實作 PR。
核心變更和重構可能很難協調，因為 PyTorch 主分支的開發速度非常快。對於根本性或跨領域的變更，請務必與我們聯繫；我們通常可以提供關於如何將這些變更分階段放入更容易審閱的部分的指導。
開始寫程式！
請參閱 CONTRIBUTING.md 檔案，以取得關於以技術形式使用 PyTorch 的建議。
開啟一個 Pull Request。
如果您還沒準備好讓 Pull Request 接受審閱，請先建立一個草稿 Pull Request - 您稍後可以按下「Ready for review」按鈕將其轉換為完整的 PR。您也可以在草稿階段，在 PR 標題前加上 "[WIP]"（"work in progress"）。我們在進行審閱時會忽略草稿 PR。如果您正在進行複雜的變更，最好從草稿開始，因為您需要花時間查看 CI 結果，以查看是否一切順利。
為您的變更找到合適的審閱者。我們有一些人會定期查看 PR 佇列，並嘗試審閱所有內容，但如果您恰好知道受您的 Patch 影響的給定子系統的維護者是誰，請隨時直接將他們包含在 Pull Request 中。您可以了解更多關於可能審閱您程式碼的 Persons of Interest。
反覆修改 Pull Request，直到它被接受！
我們會盡力減少審閱往返的次數，並且僅在出現重大問題時阻止 PR。對於 Pull Request 中最常見的問題，請查看 常見錯誤。
一旦 Pull Request 被接受並且 CI 通過，您就不需要再做任何事情；我們會為您合併 PR。
開始使用¶
提案新功能¶
新功能的想法最好在特定的 issue 上討論。請盡可能包含您能提供的資訊、任何隨附的資料，以及您提出的解決方案。PyTorch 團隊和社群經常審閱新的 issue 和評論，並在他們認為可以提供協助的地方提供協助。如果您對您的解決方案有信心，請繼續實作它。
回報 Issue¶
如果您發現了一個 issue，請先搜尋 repo 上的 現有 issue 清單。如果您找不到類似的 issue，請建立一個新的 issue。提供您可以重現問題行為的盡可能多的資訊。此外，請包含任何其他見解，例如您期望的行為。
實作功能或修正錯誤¶
如果您想修正特定的 issue，最好在個別的 issue 上評論您的意圖。但是，除了我們之前與開發者合作過的情況外，我們不會鎖定或分配 issue。最好在 issue 上開始對話並討論您提出的解決方案。PyTorch 團隊可以提供可以節省您時間的指導。
標記為 first-new-issue、low 或 medium priority 的 issue 提供了最佳的入口點，是開始的好地方。
新增教學¶
pytorch.org 上的許多教學來自社群本身，我們歡迎更多貢獻。要了解更多關於如何貢獻新的教學，您可以在這裡了解更多：GitHub 上的 PyTorch.org 教學貢獻指南
改進文件 & 教學¶
我們的目標是產出高品質的文件和教學。在極少數情況下，內容會包含錯字或錯誤。如果您發現可以修正的東西，請發送 Pull Request 給我們考慮。
請查看 文件 章節，以了解我們的系統如何運作。
參與線上討論¶
您可以在 PyTorch 討論區（適用於使用者）以及 PyTorch 開發者討論區（適用於開發者和維護者）上找到正在進行的活躍討論。
提交 Pull Request 以修正開啟的 Issue¶
您可以在這裡查看所有開啟的 Issue 清單。在 issue 上評論是引起團隊注意的好方法。從這裡您可以分享您的想法以及您計劃如何解決 issue。
對於更具挑戰性的 issue，團隊將提供關於如何最好地解決 issue 的反饋和方向。
如果您無法自行修正 issue，評論並分享您是否可以重現 issue 可以幫助團隊識別問題區域。
審閱開啟的 Pull Request¶
我們感謝您協助審閱 Pull Request 並發表評論。我們的團隊努力使開啟的 Pull Request 的數量保持在可管理的範圍內，如果我們需要更多資訊，我們會迅速回應，並且我們會合併我們認為有用的 PR。但是，由於高度的興趣，我們始終感謝更多人關注 Pull Request。
改善程式碼可讀性¶
改善程式碼可讀性對大家都有幫助。提交少數修改少量檔案的 Pull Request 通常比提交修改大量檔案的大型 Pull Request 更好。在 PyTorch 論壇這裡或在與您的改進相關的 Issue 中發起討論，是最好的入門方式。
新增測試案例以使程式碼庫更加穩健¶
額外的測試覆蓋率是值得讚賞的。
推廣 PyTorch¶
在您的專案、研究論文、文章、部落格或網路上的一般討論中使用 PyTorch，有助於提高 PyTorch 及其不斷成長的社群的知名度。請聯絡 marketing@pytorch.org 以獲得行銷支持。
問題分流 (Triaging Issues)¶
如果您認為某個 Issue 可以從特定標籤或複雜程度中受益，請在 Issue 上發表評論並分享您的意見。如果您覺得某個 Issue 的分類不正確，請發表評論並告知團隊。
關於開源開發¶
如果這是您第一次參與開源專案，那麼開發過程的某些方面可能對您來說不太尋常。
沒有「聲稱」Issue 的方法。 人們經常想在決定處理 Issue 時「聲稱」它，以確保在其他人最終處理它的時候不會浪費工作。但在開源中，這實際上效果不佳，因為有人可能會決定處理某件事，但最終沒有時間去做。 歡迎以建議的方式提供資訊，但歸根結底，我們將採用可運行的程式碼和粗略的共識來快速推進。
新功能的門檻很高。 與公司環境不同，在公司環境中，編寫程式碼的人隱含地「擁有」程式碼，並且可以預期在程式碼的整個生命週期中照顧它，但是一旦 Pull Request 合併到開源專案中，它立即成為專案上所有維護者的集體責任。 當我們合併程式碼時，我們表示我們（維護者）可以審查後續更改並對程式碼進行錯誤修復。 這自然會導致更高的貢獻標準。
要避免的常見錯誤¶
您是否新增了測試？（或者，如果變更難以測試，您是否描述了如何測試您的變更？）
我們要求進行測試有幾個動機
幫助我們判斷以後是否會破壞它
幫助我們判斷補丁一開始是否正確（是的，我們確實審查了它，但是正如 Knuth 所說：「請注意以下程式碼，因為我沒有運行它，只是證明它是正確的」）
什麼時候可以不新增測試？ 有時，變更可能不方便進行測試，或者變更顯然是正確的（並且不太可能被破壞），因此可以不進行測試。 相反地，如果某個變更似乎可能（或已知可能）被意外破壞，那麼花時間制定測試策略非常重要。
您的 PR 太長了嗎？
我們更容易審查和合併小的 PR。 審查 PR 的難度與其大小成非線性關係。
什麼時候可以提交大型 PR？ 如果在 Issue 中有相應的設計討論，並且經過將要審查您的 Diff 的人員的簽署，那麼會非常有幫助。 我們還可以幫助提供有關如何將大型變更拆分為可單獨發布的部分的建議。 同樣地，如果對 PR 的內容有完整的描述，也會有所幫助：如果我們知道裡面有什麼，審查程式碼會更容易！
對細微之處的評論？ 如果您的程式碼的行為很微妙，請包含額外的評論和文件，以便我們更好地理解您的程式碼的意圖。
您是否新增了 Hack？ 有時，正確的答案是一個 Hack。 但通常，我們必須討論它。
您是否要接觸一個非常核心的元件？ 為了防止重大衰退，接觸核心元件的 Pull Request 會受到額外的審查。 在進行重大變更之前，請務必與團隊討論您的變更。
想要新增一個新功能？ 如果您想新增新功能，請在相關的 Issue 上評論您的意圖。 我們的團隊會嘗試評論並向社群提供回饋。 最好在構建新功能之前與團隊和社群的其他成員進行公開討論。 這有助於我們了解您正在做的事情，並增加它被合併的機會。
您是否接觸了與 PR 無關的程式碼？ 為了幫助程式碼審查，請僅在您的 Pull Request 中包含與您的變更直接相關的檔案。
常見問題¶
我如何以審閱者的身份貢獻？ 如果社群開發人員重現問題、嘗試新功能或以其他方式幫助我們識別或解決問題，那麼就有很多價值。 在任務或 Pull Request 上評論您的環境詳細資訊會很有幫助，並且非常感謝。
CI 測試失敗了，這意味著什麼？ 也許您的 PR 是基於一個損壞的 Main 分支？ 您可以嘗試在最新的 Main 分支之上重新 Base 您的變更。 您也可以在https://hud.pytorch.org/上查看 Main 分支的 CI 的目前狀態。
哪些是風險最高的變更？ 任何接觸構建設定的變更都是一個危險區域。 除非您事先與團隊進行了討論，否則請避免更改這些內容。
嘿，一個 Commit 出現在我的分支上，這是怎麼回事？ 有時，其他社群成員會為您的 Pull Request 或分支提供補丁或修復程式。 這通常是為了讓 CI 測試通過所需要的。
關於文檔¶
Python 文檔¶
PyTorch 文檔是使用 Sphinx 從 Python 原始碼產生的。 產生的 HTML 會複製到 pytorch.github.io 的 Main 分支中的 Docs 資料夾中，並透過 GitHub Pages 提供服務。
C++ 文檔¶
對於 C++ 程式碼，我們使用 Doxygen 來產生內容檔案。 C++ 文檔是在一個特殊的伺服器上構建的，產生的檔案會複製到 https://github.com/pytorch/cppdocs 儲存庫中，並透過 GitHub Pages 提供服務。
教學¶
PyTorch 教學是文件，用於幫助理解如何使用 PyTorch 來完成特定任務或理解更全面的概念。 教學是使用 Sphinx-Gallery 從可執行的 Python 原始碼檔案或從重新建構的文字 (rst) 檔案構建的。
教學構建概述¶
對於教學文件，Pull Request 會觸發使用 CircleCI 重新建置整個網站，以測試變更的效果。此建置會被分片成 9 個工作節點來進行建置，總共需要約 40 分鐘。同時，我們使用 make html-noplot 進行 Netlify 建置，此建置會在不將 Notebook 輸出渲染成頁面的情況下建置網站，以便快速檢閱。
在 PR 被接受後，網站會使用 GitHub Actions 重新建置並部署。
貢獻新的教學文件¶
請參閱 PyTorch.org 教學文件貢獻指南。
