貢獻 TensorFlow 程式碼

無論您是要新增損失函數、改善測試涵蓋率，還是撰寫重大設計變更的 RFC，貢獻者指南的這部分都會協助您開始。感謝您為改善 TensorFlow 所做的努力和貢獻。

開始之前

在您將原始碼貢獻給 TensorFlow 專案之前，請先查看專案 GitHub 存放區中的 CONTRIBUTING.md 檔案。例如，請參閱核心 TensorFlow 存放區中的 CONTRIBUTING.md 檔案。所有程式碼貢獻者都必須簽署貢獻者授權合約 (CLA)。

為了避免重複作業，請查看目前或建議的 RFC，並在開始處理非小功能之前，透過 TensorFlow 論壇 (developers@tensorflow.org) 聯絡開發人員。我們在決定新增功能時會有所選擇，而貢獻和協助專案的最佳方式是處理已知問題。

新貢獻者的問題

新貢獻者在搜尋首次為 TensorFlow 程式碼庫貢獻時，應尋找以下標籤。我們強烈建議新貢獻者先處理「適合新手」和「歡迎貢獻」專案；這有助於貢獻者熟悉貢獻工作流程，並讓核心開發人員熟悉貢獻者。

如果您有興趣招募團隊來協助解決大規模問題或新功能，請寄送電子郵件至 developers@ 群組，並查看我們目前的 RFC 清單。

程式碼審查

程式碼庫的新功能、錯誤修正和任何其他變更都必須經過程式碼審查。

審查以提取要求形式貢獻給專案的程式碼是 TensorFlow 開發的重要環節。我們鼓勵任何人開始審查其他開發人員提交的程式碼，特別是如果您可能會使用該功能。

以下是在程式碼審查過程中需要記住的一些問題

  • 我們要在 TensorFlow 中加入這個嗎？ 它可能會被使用嗎？身為 TensorFlow 使用者，您喜歡這項變更並打算使用它嗎？這項變更是否在 TensorFlow 的範圍內？維護新功能的成本是否值得其效益？
  • 程式碼是否與 TensorFlow API 一致？ 公用函式、類別和參數是否已妥善命名且設計直觀？

  • 是否包含文件？ 所有公用函式、類別、參數、傳回類型和儲存的屬性是否都根據 TensorFlow 慣例命名並清楚記錄？TensorFlow 的文件中是否說明了新功能，並在可能的情況下以範例說明？文件是否正確呈現？

  • 程式碼是否易於閱讀？ 程式碼的冗餘是否過高？是否應改善變數名稱以提高清晰度或一致性？是否應新增註解？是否應移除任何無用或多餘的註解？

  • 程式碼是否有效率？ 是否可以輕鬆重寫以更有效率地執行？

  • 程式碼是否向下相容於先前版本的 TensorFlow？

  • 新程式碼是否會增加對其他程式庫的新依附元件？

測試並改善測試涵蓋率

高品質的單元測試是 TensorFlow 開發流程的基石。為此，我們使用 Docker 映像檔。測試函式已適當命名，並負責檢查演算法的有效性以及程式碼的不同選項。

所有新功能和錯誤修正都必須包含足夠的測試涵蓋率。我們也歡迎貢獻新的測試案例或改善現有測試。如果您發現我們現有的測試不完整 (即使目前沒有造成錯誤)，請提出問題，並在可能的情況下提出提取要求。

如需每個 TensorFlow 專案中測試程序的具體詳細資訊，請參閱 GitHub 上專案存放區中的 README.md 和 CONTRIBUTING.md 檔案。

足夠測試中特別關注的事項

  • 每個公用函式和類別是否都經過測試？
  • 是否測試了一組合理的參數、其值、值類型和組合？
  • 測試是否驗證程式碼是正確的，以及它是否執行文件所說的程式碼預期執行的動作？
  • 如果變更是錯誤修正，是否包含非迴歸測試？
  • 測試是否通過持續整合建置？
  • 測試是否涵蓋每一行程式碼？ 如果沒有，例外情況是否合理且明確？

如果您發現任何問題，請考慮協助貢獻者瞭解這些問題並解決這些問題。

改善錯誤訊息或記錄

我們歡迎改善錯誤訊息和記錄的貢獻。

貢獻工作流程

程式碼貢獻 (錯誤修正、新開發、測試改善) 都遵循以 GitHub 為中心的工作流程。若要參與 TensorFlow 開發，請設定 GitHub 帳戶。然後

  1. Fork 您計劃處理的存放區。前往專案存放區頁面並使用「Fork」按鈕。這會在您的使用者名稱下建立存放區的副本。(如需如何 Fork 存放庫的詳細資訊，請參閱本指南。)

  2. 將存放區複製到您的本機系統。

    $ git clone git@github.com:your-user-name/project-name.git

  3. 建立新分支以保留您的工作。

    $ git checkout -b new-branch-name

  4. 處理您的新程式碼。撰寫並執行測試。

  5. Commit 您的變更。

    $ git add -A

    $ git commit -m "在此處輸入 commit 訊息"

  6. 將您的變更推送至您的 GitHub 存放庫。

    $ git push origin branch-name

  7. 開啟提取要求 (PR)。前往 GitHub 上的原始專案存放區。系統會顯示一則訊息，說明您最近推送的分支，詢問您是否要開啟提取要求。依照提示操作、跨存放庫比較，並提交 PR。這會將電子郵件傳送給提交者。您可能需要考慮將電子郵件傳送至郵寄清單，以提高可見度。(如需詳細資訊，請參閱關於 PR 的 GitHub 指南。

  8. 維護人員和其他貢獻者將審查您的 PR。請參與對話，並嘗試進行任何要求的變更。PR 獲得核准後，程式碼將會合併。

在處理您的下一個貢獻之前，請確保您的本機存放庫是最新的。

  1. 設定上游遠端。(您只需為每個專案執行一次，而不是每次都執行。)

    $ git remote add upstream git@github.com:tensorflow/project-repo-name

  2. 切換到本機 master 分支。

    $ git checkout master

  3. 從上游提取變更。

    $ git pull upstream master

  4. 將變更推送至您的 GitHub 帳戶。(選用，但良好的做法。)

    $ git push origin master

  5. 如果您要開始新工作，請建立新分支。

    $ git checkout -b branch-name

其他 git 和 GitHub 資源

貢獻者檢查清單