为 JAX 做贡献#

每个人都可以为 JAX 做出贡献,我们重视每个人的贡献。 有几种贡献方式,包括

JAX 项目遵循 Google 开源社区指南

贡献方式#

我们欢迎提交 pull request,特别是那些标记为欢迎贡献适合初学者的问题。

对于其他提案,我们希望您首先打开一个 GitHub IssueDiscussion,以寻求对您计划贡献的反馈。

使用 pull request 贡献代码#

我们所有的开发都使用 git,因此假定您具备基本知识。

请按照以下步骤贡献代码

  1. 签署 Google 贡献者许可协议 (CLA)。有关详细信息,请参阅下面的 Pull Request 检查清单。

  2. 点击 存储库页面 上的 Fork 按钮,Fork JAX 存储库。这会在您的帐户中创建 JAX 存储库的副本。

  3. 在本地安装 Python >= 3.10 以运行测试。

  4. 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.
    
  5. 将 JAX 存储库添加为上游远程,以便您可以使用它来同步更改。

    git remote add upstream https://www.github.com/jax-ml/jax
    
  6. 创建一个分支,您将在其中进行开发

    git checkout -b name-of-change
    

    使用您喜欢的编辑器(我们推荐 Visual Studio Code)实现更改。

  7. 通过从存储库顶部运行以下命令,确保您的代码通过 JAX 的 lint 和类型检查

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

    有关详细信息,请参阅Linting 和类型检查

  8. 通过从存储库顶部运行以下命令,确保测试通过

    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 还提供了对运行哪些特定测试的更精细控制;有关详细信息,请参阅运行测试

  9. 在您对更改感到满意后,按如下方式创建提交(如何编写提交消息

    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

  10. 从 JAX 存储库创建 pull request 并将其发送以供审查。在准备 PR 时,请查看JAX pull request 检查清单,如果您需要有关使用 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 命令可能对此有所帮助。

Linting 和类型检查#

JAX 使用 mypyruff 来静态测试代码质量;在本地运行这些检查的最简单方法是通过 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 上的容差不同是很常见的。