程式碼庫開發指南#

程式碼規範#

寫出好的程式碼不僅在於你寫了什麼，更在於你是如何寫的。在持續整合測試期間，會有多個工具來檢查您的程式碼是否存在風格錯誤。良好的程式設計風格是提交程式碼到 Xinference 的要求之一。

此外，不要對程式碼進行突然的更改，這可能會導致大量用戶程式碼出現問題。所以，我們需要盡可能地保持向後相容，以避免大規模的故障。

自動修復格式錯誤#

此外，持續整合將使用 pre-commit hooks 執行如 black、flake8、isort 等程式碼格式檢查工具。任何由這些檢查產生的警告都將導致持續整合失敗。因此，建議在提交程式碼之前自行執行這些檢查。可以在 Xinference 倉儲的根目錄下安裝 pre-commit 來完成此操作：

pip install pre-commit

然後執行命令：

pre-commit install

安裝好後，就能確保每次提交變更時，都會自動執行所有的樣式檢查，無需手動逐一執行。此外，使用 pre-commit 也能讓您更輕鬆地在我們的程式碼檢查發生變更時保持同步。

請注意，如果需要，您可以透過使用 git commit --no-verify 指令來跳過這些檢查。

如果您不想將 pre-commit 作為工作流程的一部分，仍然可以執行以下命令來使用它進行檢查：

pre-commit run --files <files you have modified>

而不需要事先執行 pre-commit install。

如果您想在所有最近提交的檔案上執行檢查，您可以使用以下命令：

pre-commit run --from-ref=upstream/main --to-ref=HEAD --all-files

而不需要事先執行 pre-commit install。

備註

您可以考慮定期執行 pre-commit gc 指令來清理不再使用的儲存庫。

備註

如果您安裝了衝突的 virtualenv 版本，可能會導致錯誤 - 可以參考 這裡 。

此外，由於 virtualenv 中的一個 錯誤 ，如果您使用 conda，可能會遇到問題。要解決這個問題，您可以將 virtualenv 降級到版本 20.0.33。

向後兼容#

請盡量保持向後相容性。如果您認為必須進行變更，請在拉取請求中清楚說明原因。同時，在更改方法簽名時要小心，並在需要時加入棄用警告。此外，為棄用的函式或方法加入棄用的 Sphinx 指令。

此外，您還需要

  1. 編寫一個新的測試範例，在呼叫帶有棄用參數時會發出警告。

  2. 更新所有 Xinference 現有的測試範例和程式碼，以使用新的參數。

類型提示#

Xinference 強烈鼓勵使用 PEP 484 風格的類型提示。新的開發應包含類型提示，並且對現有程式碼進行註解的拉取請求也是可以接受的！

測試驅動開發#

Xinference 非常重視測試，並強烈鼓勵貢獻者採用 測試驅動開發 (TDD)。這種開發過程「依賴於非常短的開發週期重複：首先，開發者編寫一個（初始為失敗的）自動化測試案例來定義所需的改進或新功能，然後用最少的程式碼來通過該測試。」因此，在實際撰寫任何程式碼之前，您應該先編寫您的測試案例。通常，測試案例可以從原始的 GitHub issue 中獲取。然而，值得考慮額外的情況並編寫相應的測試案例。

在將程式碼推送到 Xinference 之後，經常會要求添加測試範例。因此，養成提前編寫測試範例的習慣非常重要，這樣就不會出現問題。