備註

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

PyTorch 貢獻指南

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

貢獻流程

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

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

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

• 找出您要處理的內容。大多數開放原始碼貢獻都來自於人們解決自己遇到的問題。但是，如果您不知道要處理什麼，或者只是想更熟悉這個專案，以下是一些關於如何找到合適任務的技巧

  • 瀏覽問題追蹤器，看看是否有任何您知道如何解決的問題。經其他貢獻者確認的問題通常比較值得研究。我們也會針對適合新手的問題維護一些標籤，例如新手訓練營和1 小時，不過這些標籤的維護程度較低。

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

• 確定您的變更範圍，如果變更很大，請在 GitHub 問題上徵求設計意見。大多數的拉取請求都很小；在這種情況下，不需要讓我們知道您要做什麼，直接開始動手即可。但是，如果變更很大，通常最好先提交 RFC，以取得一些設計意見。

  • 如果您不知道變更的規模會有多大，我們可以協助您判斷！只要在問題或開發者討論區上發布即可。

  • 有些功能的添加非常標準化；例如，很多人會在 PyTorch 中添加新的運算子或優化器。在這些情況下，設計討論主要歸結為：「我們是否需要這個運算子/優化器？」提供其效用的證據，例如在同行評審論文中的使用，或在其他框架中的存在，在提出這個案例時會有所幫助。

    • 添加最近發表的研究中的運算子/演算法通常是不被接受的，除非有壓倒性的證據表明這項新發表的工作具有突破性的成果，並且最終將成為該領域的標準。如果您不確定您的方法屬於哪一種，請先提出問題，然後再實作 PR。

  • 核心變更和重構可能很難協調，因為 PyTorch 主分支的開發速度非常快。請務必針對基本或跨領域的變更與我們聯繫；我們通常可以提供關於如何將這些變更分階段進行成更容易審查的部分的指導。

• 將其編寫出來！

  • 如需以技術形式使用 PyTorch 的建議，請參閱CONTRIBUTING.md檔案。

• 發起拉取請求。

  • 如果您尚未準備好要審查拉取請求，請先建立草稿拉取請求 - 之後您可以透過按下「準備好審查」按鈕將其轉換為正式的 PR。您也可以在 PR 標題前加上「[WIP]」（「進行中」），表示它仍在草稿階段。我們在進行審查時會忽略草稿 PR。如果您正在進行複雜的變更，最好先以草稿的形式開始，因為您需要花時間查看 CI 結果，以瞭解是否成功。

  • 為您的變更尋找合適的審閱者。我們有一些人會定期瀏覽 PR 佇列並嘗試審查所有內容，但如果您碰巧知道誰是您的修補程式所影響的特定子系統的維護者，請隨時將他們直接包含在拉取請求中。您可以瞭解更多關於可以審查您程式碼的相關人士。

• 迭代拉取請求，直到它被接受！

  • 我們會盡力減少審查往返的次數，並且只會在出現重大問題時才會阻止 PR。如需拉取請求中最常見問題的說明，請參閱常見錯誤。

  • 一旦拉取請求被接受且 CI 通過，您就不需要再做任何事情；我們會為您合併 PR。

開始使用

提議新功能

最佳的新功能構想是在特定議題中討論。請盡可能包含所有資訊、任何隨附資料，以及您建議的解決方案。PyTorch 團隊和社群會定期審閱新的議題和留言，並在他們認為可以提供協助的地方提供幫助。如果您對自己的解決方案有信心，請放手實作。

回報問題

如果您發現問題，請先在儲存庫的現有問題清單中搜尋。如果您找不到類似的問題，請建立新的問題。請提供盡可能多的資訊以重現有問題的行為。此外，請包含任何額外的見解，例如您預期的行為。

實作功能或修正錯誤

如果您想修正特定問題，最好在個別問題中留言說明您的意圖。但是，除非我們之前與開發人員合作過，否則我們不會鎖定或指派問題。最好是在問題上展開對話，並討論您提出的解決方案。PyTorch 團隊可以提供指導，為您節省時間。

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

新增教學課程

pytorch.org 上的許多教學課程都來自社群本身，我們歡迎更多貢獻。如需瞭解如何貢獻新的教學課程，請參閱：GitHub 上的 PyTorch.org 教學課程貢獻指南

改進文件與教學課程

我們的目標是製作高品質的文件和教學課程。在極少數情況下，內容可能包含錯字或錯誤。如果您發現可以修正的地方，請傳送提取請求給我們審核。

請參閱「文件」一節，瞭解我們的系統如何運作。

參與線上討論

您可以在PyTorch 討論區找到針對使用者的熱烈討論，以及在PyTorch 開發人員討論區找到針對開發人員和維護人員的討論。

提交提取請求以修正未解決的問題

您可以在此查看所有未解決問題的清單。在問題中留言是引起團隊注意的好方法。您可以在此分享您的想法以及您計畫如何解決問題。

對於較具挑戰性的問題，團隊將提供如何最佳解決問題的回饋和方向。

如果您無法自行修正問題，留言並分享您是否可以重現問題，可以幫助團隊找出問題所在。

審閱未合併的提取請求

我們感謝您協助審閱和評論提取請求。我們的團隊致力於將未合併的提取請求數量保持在可管理的範圍內，如果需要更多資訊，我們會迅速回應，並且會合併我們認為有用的提取請求。但是，由於關注程度很高，因此我們始終歡迎更多人參與審閱提取請求。

改進程式碼可讀性

改進程式碼可讀性對每個人都有幫助。通常最好是提交少量僅涉及幾個檔案的提取請求，而不是提交涉及許多檔案的大型提取請求。在 PyTorch 論壇這裡或與您的改進相關的議題中展開討論是最好的開始方式。

新增測試案例以提高程式碼庫的穩固性

歡迎提供額外的測試涵蓋範圍。

推廣 PyTorch

您在專案、研究論文、報告、部落格或網際網路上的公開討論中使用 PyTorch，有助於提高人們對 PyTorch 和我們不斷成長的社群的認識。如需行銷支援，請聯絡 marketing@pytorch.org。

分類問題

如果您認為某個問題可以從特定標籤或複雜程度中受益，請在該問題中留言並分享您的意見。如果您認為某個問題的分類不正確，請留言告知團隊。

關於開放原始碼開發

如果這是您第一次為開放原始碼專案做出貢獻，開發過程中的一些面向可能會讓您覺得不尋常。

• **沒有辦法「認領」問題。**人們在決定處理某個問題時，通常會想要「認領」該問題，以確保當其他人最終也處理該問題時，不會浪費工作。這在開放原始碼中並不可行，因為有人可能會決定處理某件事，但最終卻沒有時間去做。歡迎您以建議的方式提供資訊，但最終我們會採用可執行的程式碼和大致的共識來快速推進。

• **新功能的門檻很高。**與企業環境不同，在企業環境中，撰寫程式碼的人會隱含地「擁有」程式碼，並且可以預期在程式碼的生命週期內負責維護它，而一旦提取請求被合併到開放原始碼專案中，它就會立即成為專案中所有維護人員的共同責任。當我們合併程式碼時，我們是在說我們（維護人員）可以審閱後續的變更，並對程式碼進行錯誤修正。這自然會導致更高的貢獻標準。

應避免的常見錯誤

• **您是否新增了測試？**（或者，如果變更難以測試，您是否說明了您如何測試變更？）

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

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

    2. 幫助我們判斷修補程式一開始是否正確（是的，我們確實審閱過它，但正如 Knuth 所說：「請注意以下程式碼，因為我沒有執行它，只是證明它是正確的」）

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

• 您的提取請求是否太長？

  • 我們審閱和合併小型提取請求會更容易。審閱提取請求的難度會隨著其大小非線性地增加。

  • 什麼時候可以提交大型提取請求？如果在議題中有相應的設計討論，並且獲得將要審閱您差異的人員的簽署，這將會很有幫助。我們也可以就如何將大型變更拆分為可個別發佈的部分提供建議。同樣地，如果對提取請求的內容有完整的描述，這也會有所幫助：如果我們知道裡面有什麼，審閱程式碼會更容易！

• **針對微妙之處的註解？**如果您的程式碼行為很微妙，請包含額外的註解和文件，以便我們更好地理解您的程式碼意圖。

• **您是否新增了臨時解決方案？**有時，正確的答案是臨時解決方案。但通常情況下，我們必須討論它。

• **您是否想要修改非常核心的元件？**為了防止重大的回歸，修改核心元件的提取請求會受到額外的審查。在進行重大變更之前，請確保您已與團隊討論過您的變更。

• **想要新增新功能？**如果您想要新增新功能，請在相關議題中留言說明您的意圖。我們的團隊會盡力對社群的留言做出回應並提供回饋。在建構新功能之前，最好先與團隊和社群的其他成員進行公開討論。這有助於我們瞭解您正在做的事情，並提高它被合併的機率。

• **您是否修改了與提取請求無關的程式碼？**為了協助程式碼審閱，請僅在您的提取請求中包含與您的變更直接相關的檔案。

常見問題

• **我該如何以審閱者的身分做出貢獻？**如果社群開發人員可以重現問題、試用新功能，或者以其他方式幫助我們找出或排除問題，這將會非常有價值。歡迎您在任務或提取請求中留言，並提供您的環境詳細資訊。

• **CI 測試失敗，這是什麼意思？**也許您的提取請求是基於損壞的主分支？您可以嘗試將您的變更重新建立在最新的主分支之上。您也可以在 https://hud.pytorch.org/ 查看主分支 CI 的目前狀態。

• **風險最高的變更是什麼？**任何修改建構設定的動作都是高風險的。除非您事先與團隊討論過，否則請避免變更這些設定。

• **嘿，我的分支上出現了一個提交，這是怎麼回事？**有時，其他社群成員會為您的提取請求或分支提供修補程式或修正程式。這通常是為了讓 CI 測試通過所必需的。

關於文件

Python 文件

PyTorch 文件是使用 Sphinx 從 Python 原始碼產生的。產生的 HTML 會複製到 pytorch.github.io 主分支中的 docs 資料夾，並透過 GitHub Pages 提供。

• 網站：https://pytorch.com.tw/docs

• GitHub：https://github.com/pytorch/pytorch/tree/main/docs

• 提供來源：https://github.com/pytorch/pytorch.github.io/tree/master/docs

C++ 文件

對於 C++ 程式碼，我們使用 Doxygen 來產生內容檔案。C++ 文件是在特殊的伺服器上建構的，產生的檔案會複製到 https://github.com/pytorch/cppdocs 儲存庫，並透過 GitHub Pages 提供。

• 網站：https://pytorch.com.tw/cppdocs

• GitHub：https://github.com/pytorch/pytorch/tree/main/docs/cpp

• 提供來源：https://github.com/pytorch/cppdocs

教學課程

PyTorch 教學文件旨在協助您了解如何使用 PyTorch 完成特定任務或理解更全面的概念。教學文件是使用可執行的 Python 原始程式碼檔案或 restructured-text (rst) 檔案，透過 Sphinx-Gallery 建立的。

• 網站：https://pytorch.com.tw/tutorials

• GitHub：https://github.com/pytorch/tutorials

教學文件建置概觀

對於教學文件，提取請求 會觸發使用 CircleCI 重新建置整個網站，以測試變更的影響。此建置會分片成 9 個工作線程建置，總共需要約 40 分鐘。同時，我們會使用 make html-noplot 進行 Netlify 建置，它會在不將筆記本輸出轉譯成頁面的情況下建置網站，以便快速審閱。

提取請求被接受後，網站會使用 GitHub Actions 重新建置和部署。

貢獻新的教學文件

請參閱 PyTorch.org 教學文件貢獻指南。