PyTorch 貢獻指南

原文：PyTorch 貢獻指南

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

PyTorch 貢獻過程

PyTorch 組織受 PyTorch 治理管轄。

PyTorch 開發(fā)過程涉及核心開發(fā)團隊和社區(qū)之間的大量公開討論。

PyTorch 的運行與 GitHub 上的大多數開源項目相似。 但是，如果您以前從未為開源項目做過貢獻，那么這是基本過程。

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

入門

提出新功能

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

報告問題

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

實施功能或修復錯誤

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

標為“新發(fā)行”，“低”或“中”優(yōu)先級的問題是最好的切入點，是一個很好的起點。

添加教程

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

改進文檔&教程

我們旨在制作高質量的文檔和教程。 在極少數情況下，內容包括錯別字或錯誤。 如果您發(fā)現可以解決的問題，請向我們發(fā)送請求以供考慮。

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

參加在線討論

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

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

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

對于更具挑戰(zhàn)性的問題，團隊將為如何最好地解決問題提供反饋和指導。

如果您無法自行解決問題，請評論并分享您是否可以重現該問題對于幫助團隊確定問題區(qū)域很有用。

審查未完成的拉取請求

感謝您為審核請求提出評論的意見。 我們的團隊努力將公開請求的數量保持在可管理的范圍內，我們會在需要時迅速做出回應以提供更多信息，并且我們合并認為有用的 PR。 但是，由于人們的關注度很高，因此請多加關注拉取請求。

提高代碼可讀性

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

添加測試用例以使代碼庫更健壯

附加測試覆蓋范圍表示贊賞。

推廣 PyTorch

在項目，研究論文，文章，博客或互聯網上的一般性討論中使用 PyTorch 有助于提高對 PyTorch 和我們不斷發(fā)展的社區(qū)的認識。

分類問題

如果您認為某個問題可以從特定的標記或復雜性級別中受益，請對該問題發(fā)表評論并分享您的觀點。 如果您認為問題未正確歸類，請發(fā)表評論并告知團隊。

關于開源開發(fā)

如果這是您第一次為開放源代碼項目做貢獻，那么開發(fā)過程的某些方面對您來說似乎并不尋常。

• 無法“聲明”問題。 人們通常希望在決定處理某個問題時“主張”該問題，以確保在其他人最終處理該問題時不會浪費工作。 在開放源代碼中，這實際上并不是很好，因為有人可能會決定從事某項工作，最終沒有時間去做。 隨時以咨詢的方式提供信息，但最終，我們將獲得運行代碼和粗略的共識。
• 添加了新功能的較高標準。 與公司環(huán)境不同，在公司環(huán)境中，編寫代碼的人隱式“擁有”該代碼，并且可以期望在代碼生命周期的開始就對其進行處理，一旦將合并請求合并到一個開源項目中，它就會立即 成為項目所有維護者的集體責任。 當我們合并代碼時，我們是在說維護者能夠查看隨后的更改并對代碼進行錯誤修正。 這自然會導致更高的貢獻標準。

避免的常見錯誤

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

經常問的問題

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

關于文檔

Python 文檔

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

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

C ++文件

對于 C ++代碼，我們使用 Doxygen 生成內容文件。 C ++文檔建立在特殊的服務器上，并將生成的文件復制到 https://github.com/pytorch/cppdocs 存儲庫，并從 GitHub 頁面提供。

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

講解

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

• 網站： http://pytorch.org/tutorials
• GitHub： http://github.com/pytorch/tutorials

教程構建概述

對于教程，拉取請求使用 CircleCI 觸發(fā)重建整個站點，以測試更改的效果。 該建筑被分割為 9 個工人建筑，總共耗時約 40 分鐘。 同時，我們使用 make html-noplot 進行 Netlify 構建，該構建無需將筆記本輸出呈現為頁面即可快速瀏覽的站點。

接受 PR 后，可從 CircleCI 重建和部署站點。

撰寫新教程

PyTorch.org 教程貢獻指南