貢獻 TFDS 儲存庫

感謝您對我們程式庫感興趣！我們很高興能有如此積極的社群。

開始使用

  • 如果您是 TFDS 新手，最簡單的入門方式是實作我們其中一個要求提供的資料集，並著重於最常要求的資料集。請按照我們的指南取得操作說明。
  • 問題、功能要求、錯誤... 比新增資料集影響更大，因為它們有益於整個 TFDS 社群。請參閱潛在貢獻清單。從標示為 contribution-welcome 的項目開始，這些是小型的獨立簡易問題，適合新手入門。
  • 請隨時接手已指派但已有一段時間未更新的錯誤。
  • 無需將問題指派給您。開始處理問題時，只需在問題上留言即可 :)
  • 如果您對某個問題感興趣但不知道如何開始，請隨時尋求協助。如果您想要儘早取得意見回饋，請傳送 PR 草稿。
  • 為避免不必要的工作重複，請查看待處理的提取請求清單，並在您正在處理的問題上留言。

設定

複製儲存庫

若要開始使用，請複製或下載 Tensorflow Datasets 儲存庫，並在本機安裝儲存庫。

git clone https://github.com/tensorflow/datasets.git
cd datasets/

安裝開發依附元件

pip install -e .  # Install minimal deps to use tensorflow_datasets
pip install -e ".[dev]"  # Install all deps required for testing and development

請注意，還有 pip install -e ".[tests-all]" 可安裝所有資料集專用依附元件。

Visual Studio Code

使用 Visual Studio Code 開發時，我們的儲存庫隨附一些預先定義的設定，以協助開發 (正確縮排、pylint 等)。

  • 如果您遇到一些 TensorFlow 警告訊息，請嘗試此修正程式。
  • 如果探索失敗的原因是缺少應該已安裝的匯入，請傳送 PR 以更新 dev pip 安裝。

PR 檢查清單

簽署 CLA

對此專案的貢獻必須隨附「貢獻者授權協議」(CLA)。您 (或您的雇主) 保留您貢獻內容的著作權；這僅授予我們權限，可將您的貢獻內容做為專案的一部分使用和重新發布。請前往 <https://cla.developers.google.com/> 查看您目前已歸檔的協議或簽署新協議。

您通常只需提交一次 CLA，因此如果您已提交過 (即使是針對不同的專案)，可能就不需要再次提交。

遵循最佳實務

  • 可讀性很重要。程式碼應遵循最佳程式設計實務 (避免重複、分解為小型獨立函式、明確的變數名稱等)
  • 越簡單越好 (例如，將實作拆分為多個較小的獨立 PR，這樣更容易審查)。
  • 必要時新增測試，現有測試應通過。
  • 新增類型註解

檢查您的樣式指南

我們的樣式以 Google Python Style Guide 為基礎，而 Google Python Style Guide 又以 PEP 8 Python style guide 為基礎。新程式碼應嘗試遵循 Black code style，但需符合下列條件：

  • 行長度：80
  • 縮排 2 個空格，而非 4 個。
  • 單引號 '
pip install pylint --upgrade
pylint tensorflow_datasets/core/some_file.py

您可以嘗試使用 yapf 自動格式化檔案，但此工具並非完美，因此您可能仍需在之後手動套用修正。

yapf tensorflow_datasets/core/some_file.py

pylint 和 yapf 應該都已透過 pip install -e ".[dev]" 安裝，但也可以使用 pip install 手動安裝。如果您使用 VS Code，這些工具應已整合至 UI 中。

文件字串和類型註解

類別和函式應使用文件字串和類型註解記錄在文件中。文件字串應遵循 Google style。例如

def function(x: List[T]) -> T:
  """One line doc should end by a dot.

  * Use `backticks` for code and tripple backticks for multi-line.
  * Use full API name (`tfds.core.DatasetBuilder` instead of `DatasetBuilder`)
  * Use `Args:`, `Returns:`, `Yields:`, `Attributes:`, `Raises:`

  Args:
    x: description

  Returns:
    y: description
  """

新增並執行單元測試

請確保使用單元測試測試新功能。您可以透過 VS Code 介面或命令列執行測試。例如

pytest -vv tensorflow_datasets/core/

pytest 與 unittest：從歷史上看，我們一直使用 unittest 模組來編寫測試。新的測試應盡可能使用 pytest，它更簡單、更彈性、更現代，且廣為大多數著名的程式庫 (numpy、pandas、sklearn、matplotlib、scipy、six 等) 使用。如果您不熟悉 pytest，可以閱讀 pytest 指南。

DatasetBuilder 的測試很特別，並記錄在新增資料集指南中。

送出 PR 以供審查！

恭喜！如需使用提取請求的詳細資訊，請參閱 GitHub 說明。