开发者指南#

We welcome everyone’s contributions! The development of TensorCircuit is open-sourced and centered on GitHub.

参与贡献有很多方式:

  • 回答讨论区或是 issue page 上的问题。

  • 在 issue page 报告漏洞或是提出新的功能需求。

  • 通过拉取请求改进文档(文档字符串/教程)。

  • 通过拉取请求为代码库做出贡献。

拉取请求指南#

我们欢迎大家提出拉取请求。对于涉及功能增强或 API 更改的大型拉取请求,我们需要您首先打开一个 GitHub issue 来讨论您的企划。

拉取请求推荐使用以下 git 工作流进行贡献:

  • 配置您的 git 用户名和电子邮件,以使它们与您的 GitHub 帐户匹配(如果没有)。

git config user.name <GitHub name>
git config user.email <GitHub email>
  • 通过点击 GitHub 上的 Fork 按钮来分叉 TensorCircuit 库。 这将在您自己的 GitHub 帐户中创建一个独立版本的代码库。

  • 克隆您的分叉存储库并设置对官方 TensorCircuit 存储库的 upstream 引用。

git clone <your-forked-repo-git-link>
cd tensorcircuit
git remote add upstream <official-repo-git-link>
  • 在本地配置 python 环境以进行开发。推荐使用以下命令:

pip install -r requirements/requirements.txt
pip install -r requirements/requirements-dev.txt

特定的开发任务可能需要额外的软件包。

  • 从源代码 pip 安装你的 fork。这允许您在本地修改代码并立即对其进行测试。

python setup.py develop
  • 创建一个功能分支,您可以在其中进行修改和开发、不要从你的 master/main 分支打开拉取请求。

git checkout -b <name-of-change>
  • 运行 ./check_all.sh 以确保你的修改能够通过所有检查(参考 Checks 部分以获取更多细节)。

  • 一旦您对更改感到满意,请按如下方式创建提交:

git add file1.py file2.py ...
git commit -m "Your commit message (should be brief and informative)"
  • 您应该将您的代码与官方库进行同步:

git fetch upstream
git rebase upstream/master      # resolve conflicts if any
  • 请注意,拉取请求通常包含一个 git 提交,您应该在功能分支中压缩所有提交。使用 git rebase -i 压缩修改,参考 教程

  • 从您的功能分支上传您的提交。这将在您在 GitHub 上的分叉存储库中创建一个远程分支,您将从该分支中提出拉取请求。

git push --set-upstream origin <name-of-change>
  • 从官方 TensorCircuit 存储库创建拉取请求并将其发送以供审核。建议在拉取请求中附上一些评论和备注。如果拉取请求没有最终完成,请在您的拉取请求的标题前加上 [WIP]。

  • 拉取请求将由开发人员审核,并可能获得批准或被要求完善。在后一种情况下,您可以根据代码审查者的建议和反馈进一步修改拉取请求。

  • 一旦您进一步将提交上传到您的分叉存储库,您打开的拉取请求就会自动更新。请记得尽快在拉取请求对话中提醒代码审阅者。

  • 请尽可能始终为您的拉取请求包含新的文档和测试,并在 CHANGELOG 上记录您的更改。

检查#

确保代码库可以进行检查和测试的最简单方法是运行一体化脚本 ./check_all.sh (你可能需要 chmod +x check_all.sh 以在文件中获得批准)。

此脚本包含下面的部分:

  • black 库

  • mypy: 设置文件是 mypy.ini, 结果与 numpy 的版本强烈相关,我们设置 numpy==1.21.5 作为持续集成中的 mypy 标准。

  • pylint: 设置文件是 .pylintrc

  • pytest: 阅读 Pytest 部分以获取更多细节。

  • sphinx 文档产生: 参考 Docs 部分以获取更多细节。

通过💐确保脚本检查成功。

类似的测试和检查也可以通过 GitHub 持续集成基础设的施操作来实现。

还请在 CHANGELOG.md 和拉取请求的文档中包括相应更改。

Pytest#

关于 pytest,你可以通过 pip install pytest-xdist,然后并行运行 pytest -v -n [number of processes] 来加快测试速度。我们还包含了一些与 pip install pytest-benchmark 一起使用的微基准测试。

Fixtures:

我们在 conftest 文件中定义了一些 pytest fixture,用于后端自定义和函数级别的 dtype 。highp 是 complex128 模拟的 fixture 。 而 npbtfbjaxbtorchb 分别是全局 numpy、tensorflow、jax 和 pytorch 后端的 fixtures 。 要在一个函数中测试不同的后端,我们需要使用参数化的 fixtures,它由 pip install pytest-lazy-fixture 启动。也就是说,我们有以下方法在一个函数中测试不同的后端。

from pytest_lazyfixture import lazy_fixture as lf

@pytest.mark.parametrize("backend", [lf("npb"), lf("tfb"), lf("jaxb"), lf("torchb")])
def test_parameterized_backend(backend):
    print(tc.backend.name)

文档#

我们使用 sphinx 来管理文档。

文档的源文件是在 docs/source 文件夹中的 .rst 文件。

For English docs, sphinx-build source build/html and make latexpdf LATEXMKOPTS="-silent" in docs dir are enough. The html and pdf version of the docs are in docs/build/html and docs/build/latex, respectively.

Formula Environment Attention

It should be noted that the formula environment $$CONTENT$$ in markdown is equivalent to the equation environment in latex. Therefore, in the jupyter notebook documents, do not nest the formula environment in $$CONTENT$$ that is incompatible with equation in latex, such as eqnarray, which will cause errors in the pdf file built by nbsphinx. However, compatible formula environments can be used. For example, this legal code in markdown

$$
\begin{split}
    X&=Y\\
    &=Z
\end{split}
$$

will be convert to

\begin{equation}
    \begin{split}
        X&=Y\\
        &=Z
    \end{split}
\end{equation}

in latex automatically by nbsphinx, which is a legal latex code. However, this legal code in markdown

$$
\begin{eqnarray}
    X&=&Y\\
    &=&Z
\end{eqnarray}
$$

will be convert to

\begin{equation}
    \begin{eqnarray}
        X&=&Y\\
        &=&Z
    \end{eqnarray}
\end{equation}

in latex, which is an illegal latex code.

自动生成 API 文档:

我们利用 python 脚本根据代码库 /tensorcircuit 生成/刷新 /docs/source/api 下的所有 API rst 文档文件。

cd docs/source
python generate_rst.py

国际化

For Chinese docs, we refer to the standard i18n workflow provided by sphinx, see here.

为从更新的英文 rst 文件中更新 .po 文件,使用

cd docs
make gettext
sphinx-intl update -p build/gettext -l zh

Edit these .po files to add translations (poedit recommended). These files are in docs/source/locale/zh/LC_MESSAGES.

To generate the Chinese version of the documentation: sphinx-build source -D language="zh" build/html_cn which is in the separate directory .../build/html_cn/index.html, whereas English version is in the directory .../build/html/index.html.

Releases#

Firstly, ensure that the version numbers in __init__.py and CHANGELOG are correctly updated.

GitHub Release

git tag v0.x.y
git push origin v0.x.y
# assume origin is the upstream name

And from GitHub page choose draft a release from tag.

PyPI Release

python setup.py sdist bdist_wheel
export VERSION=0.x.y
twine upload dist/tensorcircuit-${VERSION}-py3-none-any.whl dist/tensorcircuit-${VERSION}.tar.gz

DockerHub Release

Make sure the DockerHub account is logged in via docker login.

sudo docker build . -f docker/Dockerfile -t tensorcircuit
sudo docker tag tensorcircuit:latest tensorcircuit/tensorcircuit:0.x.y
sudo docker push tensorcircuit/tensorcircuit:0.x.y
sudo docker tag tensorcircuit:latest tensorcircuit/tensorcircuit:latest
sudo docker push tensorcircuit/tensorcircuit:latest

Binder Release

One may need to update the tensorcirucit version for binder environment by pushing new commit in refraction-ray/tc-env repo with new version update in its requriements.txt. See mybind setup for speed up via nbgitpuller.