貢獻 JAX

貢獻 JAX#

每個人都可以為 JAX 做出貢獻，我們重視每個人所做的貢獻。有幾種貢獻方式，包括：

在 JAX 的討論頁面上回答問題
改進或擴充 JAX 的文件
貢獻 JAX 的程式碼庫
以上述任何方式貢獻給更廣泛的基於 JAX 建構的函式庫生態系統

JAX 專案遵循Google 開源社群指南。

貢獻方式#

我們歡迎 Pull Request，特別是標記為歡迎貢獻或適合新手的問題。

對於其他提案，我們要求您先開啟 GitHub Issue 或 Discussion 以尋求對您計劃貢獻的回饋。

使用 Pull Request 貢獻程式碼#

我們所有的開發都使用 git，因此假設您具備基本知識。

請按照以下步驟貢獻程式碼

簽署 Google 貢獻者授權協議 (CLA)。詳情請參閱下面的 Pull Request 檢查清單。
通過點擊儲存庫頁面上的 Fork 按鈕來 Fork JAX 儲存庫。這會在您自己的帳戶中建立 JAX 儲存庫的副本。
在本機安裝 Python >= 3.10 以執行測試。

pip 從原始碼安裝您的 Fork。這讓您可以修改程式碼並立即進行測試

git clone https://github.com/YOUR_USERNAME/jax
cd jax
pip install -r build/test-requirements.txt  # Installs all testing requirements.
pip install -e ".[cpu]"  # Installs JAX from the current directory in editable mode.

將 JAX 儲存庫新增為上游遠端，以便您可以使用它來同步您的變更。
```
git remote add upstream https://www.github.com/jax-ml/jax
```
建立一個分支，您將從該分支進行開發
```
git checkout -b name-of-change
```
並使用您最喜歡的編輯器 (我們推薦 Visual Studio Code) 實作您的變更。
通過從儲存庫的頂層執行以下命令，確保您的程式碼通過 JAX 的程式碼風格檢查和型別檢查
```
pip install pre-commit
pre-commit run --all
```
有關更多詳細資訊，請參閱程式碼風格檢查和型別檢查。
通過從儲存庫的頂層執行以下命令，確保測試通過
```
pytest -n auto tests/
```
JAX 的測試套件非常龐大，因此如果您知道涵蓋您變更的特定測試檔案，則可以將測試限制於該檔案；例如
```
pytest -n auto tests/lax_scipy_test.py
```
您可以通過使用 pytest -k 旗標來匹配特定的測試名稱，從而進一步縮小測試範圍
```
pytest -n auto tests/lax_scipy_test.py -k testLogSumExp
```
JAX 還提供更細緻的控制，以控制要運行的特定測試；有關更多資訊，請參閱運行測試。
一旦您對您的變更感到滿意，請按如下方式建立提交 ( 如何編寫提交訊息)
```
git add file1.py file2.py ...
git commit -m "Your commit message"
```
然後將您的程式碼與主儲存庫同步
```
git fetch upstream
git rebase upstream/main
```
最後，在您的開發分支上推送您的提交，並在您的 Fork 中建立一個遠端分支，您可以使用該分支來建立 Pull Request
```
git push --set-upstream origin name-of-change
```
請確保您的貢獻是單一提交 (請參閱單一變更提交和 Pull Request)
從 JAX 儲存庫建立 Pull Request 並發送以供審查。檢查JAX Pull Request 檢查清單，以了解準備 PR 時的注意事項，如果您需要更多有關使用 Pull Request 的資訊，請查閱 GitHub 幫助。

JAX Pull Request 檢查清單#

在您準備 JAX Pull Request 時，請記住以下幾點

Google 貢獻者授權協議#

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

您通常只需要提交一次 CLA，因此如果您已經提交過 CLA (即使是針對不同的專案)，您可能不需要再次提交。如果您不確定是否已簽署 CLA，您可以開啟您的 PR，我們友好的 CI 機器人會為您檢查。

單一變更提交和 Pull Request#

git 提交應該是一個自包含的、帶有描述性訊息的單一變更。這有助於審查，並有助於在以後發現問題時識別或還原變更。

Pull Request 通常包含單一 git 提交。 (在某些情況下，例如對於大型重構或內部重寫，它們可能包含多個。) 在準備用於審查的 Pull Request 時，您可能需要將多個提交合併在一起。如果可能，我們要求您在發送 PR 進行審查之前執行此操作。 git rebase -i 命令可能對此有所幫助。

程式碼風格檢查和型別檢查#

JAX 使用 mypy 和 ruff 來靜態測試程式碼品質；在本地運行這些檢查的最簡單方法是通過 pre-commit 框架

pip install pre-commit
pre-commit run --all-files

如果您的 Pull Request 涉及文件筆記本，這也將對這些筆記本運行一些檢查 (有關更多詳細資訊，請參閱更新筆記本)。

完整的 GitHub 測試套件#

您的 PR 將自動通過 GitHub CI 上的完整測試套件運行，該套件涵蓋一系列 Python 版本、依賴版本和配置選項。這些測試出現您在本地沒有捕獲到的失敗是正常的；要修復這些問題，您可以將新的提交推送到您的分支。

受限制的測試套件#

一旦您的 PR 經過審查，JAX 維護者會將其標記為 pull ready。這將觸發更大規模的測試集，包括在標準 GitHub CI 中不可用的 GPU 和 TPU 後端上的測試。這些測試的詳細結果不公開可見，但分配給您的 PR 的 JAX 維護者將與您溝通這些測試可能發現的任何失敗；例如，數值測試在 TPU 上可能需要與 CPU 上不同的容差，這並不罕見。