如何贡献

如何贡献#

每个人都可以为 Flax 贡献力量，Flax 开发团队重视每个人的贡献！除了编写代码之外，您还可以通过多种方式贡献。在Flax GitHub 讨论页面上回答问题，互相帮助以及改进 Flax 文档对 Flax 生态系统都非常有价值。

我们也感谢您宣传 Flax，例如为Flax GitHub 代码库加星标，或在使用 Flax 的项目博文中引用 Flax。

本项目遵循Google 的开源社区准则。

贡献方式#

我们欢迎拉取请求 (PR)，特别是对于那些标记为可接受 PR 的问题。对于其他提案，您应该首先打开一个 GitHub Issue 或 GitHub 讨论来开始关于您计划贡献的对话。

使用拉取请求贡献代码#

Flax 开发团队使用Git进行所有开发。要做出贡献，您应该具备Git和GitHub的基本知识。（您可以按照 Git 的官方入门 - Git 首次设置和 GitHub 的设置 Git指南学习如何设置 Git。）

要向 GitHub 上的 Flax 贡献代码，请按照以下步骤操作

从分支创建拉取请求#

  1. 使用 GitHub 的 Web UI，通过点击github.com/google/flax代码库页面上的“Fork”按钮来分叉 Flax 代码库。这会在您自己的 GitHub 中创建一个 Flax 代码库的分支（副本）。

    参考：从分支创建拉取请求。

  2. 安装Python >=3.7。

  3. (可选) 创建虚拟环境或 Docker 容器。有关如何设置 Docker 容器的详细信息，请参阅dev/README.md。要设置虚拟环境，请运行以下命令

    python3 -m virtualenv env
. env/bin/activate

    这确保所有依赖项都安装在此环境中。

  4. 使用git clone克隆您本地分叉的 Flax 代码库。然后，使用PyPi安装所需的软件包。这使您能够在修改代码后立即对其进行测试

    git clone https://github.com/YOUR_USERNAME/flax
cd flax
pip install -e ".[all,testing,docs]"

    您还可以使用uv来设置开发环境

    uv sync --all-extras

  5. 设置预提交钩子，这将在每次git提交期间运行一些自动检查，并可能更新一些需要更改的文件。

    pip install pre-commit
pre-commit install

  6. 将 Google Flax 代码库（而不是您的分支）添加为上游远程，以便您可以使用它来同步您的更改。

    git remote add upstream http://www.github.com/google/flax

  7. 创建一个分支，例如my_development_branch，您将从此分支开始开发

    git checkout -b my_development_branch

  8. 使用您喜欢的编辑器实现您的更改（我们推荐Visual Studio Code）。

    通过运行以下命令确保测试通过，该命令从代码库的顶部运行

    ./tests/run_all_tests.sh

  9. 完成更改后，不要忘记创建提交（学习如何编写提交消息）

    git add file1.py file2.py ...
# or use `git add .` to add all changed files
git commit -m "Your commit message"

    然后将您的代码与主代码库同步

    git fetch upstream
git rebase upstream/main

  10. 最后，将您的提交推送到您的my_development_branch上，并在您的分支中创建一个远程分支，您可以从中创建拉取请求

git push --set-upstream origin my_development_branch

运行该命令后，您应该在（VS Code）终端输出中获得一个用于创建拉取请求的 GitHub 链接。如果您在git push之后没有收到链接，请使用GitHub Web UI创建拉取请求。

  1. 确保您的拉取请求通过了Flax PR 检查列表。如果是，请从 Flax 代码库创建拉取请求并将其发送以供审查。有关使用拉取请求的更多信息，请咨询GitHub 帮助。

您可以在 GitHub 的从分支创建拉取请求文档中了解更多信息。

添加或更新依赖项#

要添加或更新依赖项，您必须在更新pyproject.toml文件后使用uv，以确保uv.lock文件是最新的。

uv sync --all-extras

或者，您可以使用uv add自动添加或更新依赖项，例如

uv add 'some-package>=1.2.3'

更新 Jupyter Notebooks#

我们使用jupytext在docs/notebooks中维护文档的两个同步副本：一个以 Jupyter Notebook (.ipynb) 格式，另一个以 Markdown (.md) 格式。

前者可以直接在Google Colab中打开和执行。Markdown 使在版本控制中跟踪更改/差异以及例如 GitHub Web UI 变得更容易，因为.ipynb文件基于 JSON。

编辑 Jupyter Notebooks (.ipynb)#

对于进行大幅修改代码和输出的大量更改，建议在Jupyter或Colab中编辑笔记本。

如果您选择在 Colab 中工作，请转到**文件**并点击**上传笔记本**，然后选择您的文件。将其加载到 Colab 中并进行编辑后，请确保运行单元格，并且没有错误。点击**运行时**，然后选择**运行全部**。完成后，点击**文件** > **下载** > **下载 ipynb**。您可能还想通过使用sphinx-build测试文件是否正确执行，如上所述。

在 Jupyter Notebook 中进行更改后，请按照下面的“同步笔记本”步骤操作。

编辑 Markdown 文件 (.md)#

对于对笔记本的文本内容进行较小的更改，最简单的方法是使用文本编辑器编辑.md版本。

在 Markdown 文件中进行更改后，请按照下面的“同步笔记本”步骤操作。

同步笔记本#

在编辑文档的.ipynb或.md版本后，使用jupytext通过在更新的笔记本上运行jupytext --sync来同步这两个版本。

首先，确保您已安装 jupytext。jupytext 版本应与.pre-commit-config.yaml中指定的版本匹配（目前，它是 v1.13.8）。

pip install jupytext==1.13.8

然后，在您对 Jupyter Notebook 进行更改后，通过运行以下命令将其内容与等效的 Markdown 文件同步

jupytext --sync path/to/the/file.ipynb

类似地，要将您的 Markdown 文件与它的 Jupyter Notebook 版本同步，请运行

jupytext --sync path/to/the/file.md

请注意，如果您收到错误，并且这是您第一次在 Jupyter Notebook 中工作，您可能需要（重新）创建文档的同步副本（这在下面的“创建新笔记本”部分中有详细说明）。

jupytext --set-formats ipynb,md:myst path/to/the/notebook.ipynb

完成 .md 和 .ipynb 文件的同步后，您可以使用 pre-commit 框架检查它们是否已正确同步，以执行 Flax GitHub CI 中使用的相同检查。

git add docs -u  # pre-commit runs on files in git staging.
pre-commit run jupytext

创建新笔记本#

如果您要向文档添加新的 Jupyter Notebook，可以使用 jupytext --set-formats。它可以设置文件的 Jupyter Notebook (.ipynb) 和 Markdown (.md) 版本。

jupytext --set-formats ipynb,md:myst path/to/the/notebook.ipynb

它的工作原理是向笔记本文件添加一个 "jupytext" 元数据字段，该字段指定所需的格式。然后，当调用 jupytext --sync 命令时，它可以识别这些格式。

在您对文件进行更改后，请按照上面“同步笔记本”部分中的步骤操作，以保持 Markdown 和 Jupyter Notebook 文件的内容同步。

Sphinx 构建中的笔记本#

一些笔记本会作为预提交检查的一部分以及 Read the Docs 构建的一部分自动构建。如果单元格引发错误，构建将失败。如果错误是故意的，您可以捕获它们，或者使用 raises-exceptions 元数据标记单元格（示例 PR）。您必须在 .ipynb 文件中手动添加此元数据。当其他人重新保存笔记本时，它将被保留。

我们从构建中排除了一些笔记本，例如，因为它们包含长时间的计算。请参阅 conf.py 中的 exclude_patterns。

更新拉取请求内容#

每个拉取请求理想情况下应仅限于一个提交，因此，如果您有多个提交，请将它们压缩。

假设您现在在拉取请求中只有一个提交，并且想要添加在审查期间请求的更改

  1. 在您的编辑器中本地进行更改。

  2. 运行 git commit -a --amend。这将更新提交内容并允许您编辑提交消息。

  3. 此时，仅使用 git push 将导致错误。相反，请使用 git push --force。

  4. 检查它是否已完成：对您的提交的更改应立即反映在 Github Web UI 中。

故障排除#

拉取请求中的提交过多#

如果您的 PR 附带了过多的提交（例如，超过五个），则需要将它们压缩。否则，Flax 文档构建过程可能会因错误消息而失败。这是由于以下原因造成的

  • 您的拉取请求中有多于五个提交；并且

  • 当提交树过大时，Flax 源同步过程会失败。

要压缩您的提交，您可以将您的分支重新定位到 main 并创建一个包含所有更改的新提交，运行以下命令

git rebase main && git reset --soft main && git commit

这会将所有更改应用于主分支。请注意，如果您在处理更改时必须解决任何冲突（例如，您执行了 pull upstream main 导致冲突），那么您将不得不再次解决这些冲突。

成功重新定位分支后，您应该推送更改。并且因为您更改了提交历史记录，您可能需要使用 git push --force。

贡献者许可协议#

对该项目的贡献必须附带贡献者许可协议。您（或您的雇主）保留对您贡献的版权；这只是简单地赋予我们权限，允许我们将您的贡献用作项目的一部分并重新分发。

您通常只需要提交一次 CLA，因此，如果您已经提交过一个（即使是针对不同的项目），您可能就不需要再次提交。

目录