評價此頁
★ ★ ★ ★ ★

注意

此頁面已棄用。請參考 PyTorch Wiki 上的 貢獻指南。

PyTorch 貢獻指南#

創建於：2019年3月11日 | 最後更新於：2025年4月27日

PyTorch 是一個 GPU 加速的 Python 張量計算庫，用於透過基於磁帶的自動微分系統構建深度神經網路。

貢獻流程#

PyTorch 組織受 PyTorch 治理 管理，貢獻的技術指南可在 CONTRIBUTING.md 中找到。

PyTorch 的開發流程涉及核心開發團隊與社群之間大量的開放式討論。

PyTorch 的運作方式與 GitHub 上大多數開源專案類似。但是，如果您以前從未為開源專案做出過貢獻，以下是基本流程。

  • 確定您要處理的內容。 大多數開源貢獻來自有自己需求的人。但是，如果您不知道要處理什麼，或者只是想更熟悉該專案，這裡有一些關於如何找到合適任務的建議：

    • 瀏覽 問題跟蹤器，看看是否有您知道如何解決的問題。其他貢獻者已確認的問題通常是更好的研究物件。我們也為可能適合新人的問題維護了一些標籤，例如 **bootcamp** 和 **1hr**，儘管這些標籤維護得不太好。

    • 加入我們的 開發討論區，讓我們知道您有興趣瞭解 PyTorch。我們非常樂意幫助研究人員和合作夥伴快速掌握程式碼庫。

  • 確定更改的範圍，如果較大，請在 GitHub issue 上徵求設計意見。 大多數 pull request 都很小；在這種情況下，無需告知我們您想做什麼，直接開始即可。但如果更改會很大，最好先透過 提交 RFC 來徵求一些設計意見。

    • 如果您不知道更改會有多大，我們可以幫助您弄清楚！只需在 issues 或 dev discuss 上釋出相關資訊。

    • 一些功能新增是非常標準化的；例如，許多人向 PyTorch 添加了新的運算元或最佳化器。在這種情況下，設計討論主要歸結為：“我們想要這個運算元/最佳化器嗎？” 提供其效用的證據，例如在同行評審論文中的使用，或在其他框架中的存在，有助於做出這一決定。

      • 新增新發布的研究所提出的運算元/演算法 通常不被接受，除非有壓倒性的證據表明這項新發表的工作具有開創性的結果，並最終將成為該領域的標準。如果您不確定您的方法屬於哪一類，請先開啟一個 issue，然後再實現 PR。

    • 核心更改和重構的協調可能相當困難，因為 PyTorch 主分支的開發速度非常快。務必就基礎性或跨領域性更改進行溝通；我們通常可以就如何將此類更改分階段進行以便於審查提供指導。

  • 編碼！

    • 有關以技術形式處理 PyTorch 的建議，請參閱 CONTRIBUTING.md 檔案。

  • 提交 pull request。

    • 如果您尚未準備好讓 pull request 被審查，請先建立一個草稿 pull request — 之後您可以按“Ready for review”按鈕將其轉換為完整的 PR。在草稿階段，您也可以在 PR 標題前加上“[WIP]”（“work in progress”）。在審查期間，我們會忽略草稿 PR。如果您正在處理一項複雜的更改，最好先將其作為草稿開始，因為您需要花費時間檢視 CI 結果，以確定事情是否按預期進行。

    • 為您的更改找到合適的審閱者。我們有一些人員會定期審查 PR 佇列並嘗試審查所有內容，但如果您碰巧知道受您的補丁影響的某個子系統的維護者是誰，請隨時將其直接包含在 pull request 中。您可以瞭解更多關於 相關人員 的資訊，他們可以審查您的程式碼。

  • 不斷迭代 pull request，直到它被接受！

    • 我們將盡最大努力減少審查的往返次數，並僅在出現重大問題時阻止 PR。對於 pull request 中最常見的問題，請檢視 常見錯誤。

    • 一旦 pull request 被接受並且 CI 透過，您就不需要做任何其他事情了；我們會為您合併 PR。

入門#

提議新功能#

最好在特定的 issue 上討論新功能想法。請包含儘可能多的資訊、任何配套資料以及您的解決方案建議。PyTorch 團隊和社群會定期審查新 issues 和評論，他們認為可以提供幫助的地方。如果您對解決方案有信心，請繼續實現它。

報告問題#

如果您發現一個問題，請先搜尋儲存庫上的 現有問題列表。如果您找不到類似的問題，則建立一個新的問題。提供儘可能多的資訊來重現問題行為。此外，還應包含任何額外的見解，例如您期望的行為。

實現功能或修復 bug#

如果您想修復一個特定的問題，最好在單個 issue 上評論您的意圖。但是，我們不會鎖定或分配 issues，除非我們之前與該開發者有過合作。最好在 issue 上開始對話並討論您建議的解決方案。PyTorch 團隊可以提供節省時間的指導。

標記為 first-new-issue、low 或 medium 優先順序的 issues 是最好的切入點，也是開始的好地方。

新增教程#

pytorch.org 上的許多教程都來自社群本身，我們歡迎更多的貢獻。要了解如何貢獻新教程，您可以在此處瞭解更多：GitHub 上的 PyTorch.org 教程貢獻指南

改進文件和教程#

我們的目標是提供高質量的文件和教程。偶爾會出現內容中的拼寫錯誤或 bug。如果您發現可以修復的地方，請向我們提交一個 pull request 以供考慮。

請檢視 文件 部分，瞭解我們的系統如何工作。

參與線上討論#

您可以在 PyTorch 討論論壇（面向使用者）以及 PyTorch 開發討論論壇（面向開發者和維護者）上找到正在進行的活躍討論。

提交 Pull Request 來修復開放的 Issue#

您可以在 此處 檢視所有開放 issue 的列表。評論 issue 是引起團隊注意的好方法。您可以在此處分享您的想法以及您計劃如何解決該 issue。

對於更具挑戰性的 issues，團隊將提供反饋和指導，說明如何最好地解決該 issue。

如果您無法自行修復該 issue，透過評論並分享您是否可以重現該 issue，可以幫助團隊識別問題區域。

審查開放的 Pull Request#

我們非常感謝您審查和評論 pull request。我們的團隊努力使開放 pull request 的數量保持在可管理的範圍內，如果我們還需要更多資訊，我們會迅速響應，並且我們會合並我們認為有用的 PR。但是，由於關注度很高，額外的眼睛審閱 pull request 總是受歡迎的。

提高程式碼可讀性#

提高程式碼可讀性對每個人都有幫助。提交少量修改幾個檔案的 pull request 通常比修改很多檔案的單個大型 pull request 要好。在 PyTorch 論壇 這裡 或與您的改進相關的 issue 上發起討論是開始的最佳方式。

為程式碼庫新增測試用例以增強其健壯性#

我們歡迎額外的測試覆蓋。

推廣 PyTorch#

您在專案、研究論文、撰寫、部落格或網際網路上的討論中使用 PyTorch 有助於提高 PyTorch 和我們不斷壯大的社群的知名度。請聯絡 marketing@pytorch.org 獲取營銷支援。

問題分類#

如果您認為一個 issue 可以從特定的標籤或複雜度級別中受益，請在 issue 上評論並分享您的意見。如果您認為某個 issue 的分類不當，請評論並告知團隊。

關於開源開發#

如果您是第一次為開源專案做出貢獻，開發過程中的某些方面可能會讓您覺得奇怪。

  • 無法“認領”issue。 人們在決定處理一個 issue 時，通常想“認領”它，以確保不會浪費工作，因為別人可能會去做。這在開源專案中並不奏效，因為有人可能會決定處理某件事，但最終沒有時間去做。您可以隨意提供建議性資訊，但最終，我們將以執行的程式碼和粗略的共識來快速推進。

  • 新功能的要求很高。 與企業環境不同，在企業環境中，編寫程式碼的人隱式地“擁有”它，並且可以預期在程式碼的整個生命週期內對其進行維護。一旦 pull request 合併到開源專案中，它就立即成為專案所有維護者的集體責任。當我們合併程式碼時，我們表示我們，即維護者，可以審查後續的更改並對程式碼進行 bug 修復。這自然導致了更高的貢獻標準。

常見錯誤避免#

  • 您是否添加了測試？（或者，如果更改難以測試，您是否描述瞭如何測試您的更改？）

    • 我們要求進行測試有幾個原因：

      1. 幫助我們判斷以後是否會破壞它

      2. 幫助我們判斷補丁是否一開始就是正確的（是的，我們審查了它，但正如 Knuth 所說，“小心以下程式碼，因為我沒有執行它，只是證明了它的正確性”）。

    • 何時可以不新增測試？有時更改不方便測試，或者更改非常明顯正確（且不太可能被破壞），因此可以不測試。相反，如果更改似乎很可能（或已知很可能）被意外破壞，那麼花時間制定測試策略就非常重要。

  • 您的 PR 是否太長？

    • 我們更容易審查和合並小的 PR。審查 PR 的難度與其大小呈非線性關係。

    • 何時可以提交一個大型 PR？如果有一個相應的 issue 設計討論，並且得到了將要審查您的 diff 的人員的認可，那將非常有幫助。我們還可以就如何將大型更改拆分成可單獨釋出的零件提供建議。同樣，如果有一個完整的 PR 內容描述，那也會有幫助：知道內容後更容易審查程式碼！

  • 對微妙之處的註釋？ 在程式碼行為微妙的情況下，請新增額外的註釋和文件，以便我們更好地理解您的程式碼的意圖。

  • 您添加了一個 hack 嗎？ 有時，正確的答案是一個 hack。但通常，我們需要對此進行討論。

  • 您想修改一個非常核心的元件嗎？ 為了防止重大回歸，修改核心元件的 pull request 會受到額外的審查。在進行重大更改之前，請務必與團隊討論您的更改。

  • 想新增一個新功能？ 如果您想新增新功能，請在相關 issue 上評論您的意圖。我們的團隊會嘗試評論並向社群提供反饋。最好在構建新功能之前與團隊和社群進行公開討論。這有助於我們瞭解您正在處理的內容，並增加其被合併的機會。

  • 您是否修改了與 PR 無關的程式碼？ 為了協助程式碼審查，請僅在您的 pull request 中包含與您的更改直接相關的檔案。

常見問題#

  • 我如何作為審閱者做出貢獻？ 社群開發者重現問題、嘗試新功能或以其他方式幫助我們識別或排除問題非常有價值。在任務或 pull request 上附帶您的環境詳細資訊會很有幫助且受到讚賞。

  • CI 測試失敗，這意味著什麼？ 也許您的 PR 基於一個損壞的主分支？您可以嘗試將您的更改重新定位到最新的主分支之上。您還可以在 https://hud.pytorch.org/ 上檢視主分支 CI 的當前狀態。

  • 哪些是風險最高的更改？ 任何涉及構建配置的更改都是高風險區域。除非您事先與團隊討論過，否則請避免更改這些內容。

  • 嘿，我的分支上出現了一個 commit，是怎麼回事？ 有時其他社群成員會為您的 pull request 或分支提供補丁或修復。這通常是 CI 測試透過所必需的。

關於文件#

Python 文件#

PyTorch 文件使用 Sphinx 從 Python 原始碼生成。生成的 HTML 會被複制到 pytorch.org/docs 的主分支的 docs 資料夾中，並透過 GitHub Pages 提供服務。

C++ 文件#

對於 C++ 程式碼，我們使用 Doxygen 來生成內容檔案。C++ 文件是在一個專用伺服器上構建的，生成的檔案會被複制到 pytorch/cppdocs 倉庫，並透過 GitHub Pages 提供服務。

教程#

PyTorch 教程是用來說明如何使用 PyTorch 完成特定任務或理解更宏觀概念的文件。教程使用 Sphinx-Gallery 從可執行的 Python 原始檔或 reStructuredText (rst) 檔案構建。

教程構建概覽#

對於教程，pull requests 會觸發使用 CircleCI 重建整個站點，以測試更改的效果。此構建被分片為 9 個工作程式構建，總計約 40 分鐘。同時，我們使用 *make html-noplot* 進行 Netlify 構建，該構建在不將 notebook 輸出渲染為頁面進行快速審查的情況下構建站點。

PR 被接受後，站點將使用 GitHub Actions 進行重建和部署。

貢獻新教程#

請參閱 PyTorch.org 教程貢獻指南。

在此頁面上
在 GitHub 上編輯
顯示原始碼
PyTorch 庫