开发者指南#
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 。 而 npb
、tfb
、jaxb
和 torchb
分别是全局 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.