为 Mars 贡献代码#

Mars 是使用 Apache License 2.0 协议的开源项目，我们欢迎和感谢您的贡献。下面是一些你在尝试改变 Mars 实现时可能觉得有用的指引。

通用指引#

Mars 使用 Github 管理和维护代码。我们对提出 Issue 及 Pull Request 提供了一套通用指引。

配置开发环境#

因为你无法在 Windows 下使用 Mars 的全部功能，除非你希望在 Windows 下部署或者调试 Mars，我们强烈建议开发者在 MacOS 或者 Linux 下开发 Mars。下面列出的步骤仅针对 MacOS 和 Linux。

在 Conda 中安装#

我们推荐使用 Conda 开发 Mars。当你希望在 Conda 中安装 Mars 用于开发，你可以使用下面的步骤创建一个 Conda 环境，并在其中安装 Mars：

git clone https://github.com/mars-project/mars.git
cd mars
conda create -n mars-dev --file conda-spec.txt python=3.7
source activate mars-dev
pip install -e ".[dev]"

将 3.7 替换为你希望安装的 Python 版本，将 mars-dev 替换为你喜欢的环境名。

其他 Python 发行版本#

Mars 拥有一个 dev 安装选项。当你希望安装 Mars 用于开发，可以使用下面的步骤：

pip install --upgrade setuptools pip
git clone https://github.com/mars-project/mars.git
cd mars
pip install -e ".[dev]"

如果你正在使用一个系统范围的 Python，且只想在这个账号里使用 Mars，可以在 pip install 命令上增加一个 --user 选项。

验证安装#

当 Mars 安装完成，你可以使用下面的步骤验证 Mars 是否正确安装：

python -c "import mars; print(mars.__version__)"

如果此命令正确输出了你的 Mars 版本，说明 Mars 已经成功安装。

重新编译 Cython 代码#

Mars 使用 Cython 加速代码执行。当你改变了 Cython 代码，你需要使用下面的命令将它们重新编译为二进制文件：

python setup.py build_ext -i

重新编译前端代码#

Mars 使用 React 编写前端，你需要安装 nodejs 完成 Mars 前端代码的构建。安装完成所有依赖后，可以使用下面的代码进行构建：

python setup.py build_web

运行测试用例#

我们推荐使用 pytest 运行 Mars 测试用例。只需要一行命令即可运行 Mars 的所有用例：

pytest mars

如果你希望在运行的同时生成代码覆盖报告，可以运行：

pytest --cov=mars --cov-report=html mars

代码覆盖报告将会被放在 htmlcov 目录下。

上面的命令默认不包含 Cython 文件的覆盖率。为获得 Cython 文件的覆盖数据，可以运行

CYTHON_TRACE=1 python setup.py build_ext -i --force

上述命令需要在前面提到的 pytest 命令之前运行。在报告生成后，建议删除所有生成的 C 文件和二进制文件，此后重新使用不带 CYTHON_TRACE 环境变量的命令编译，因为该选项会降低 Mars 的性能。

检查代码样式#

在向 Mars 提交代码前，你需要保证你的代码样式符合 Mars 项目的要求。Mars 使用 black 更正代码样式。你可以使用下面的命令格式化你的代码：

black mars

我们也要求在代码中对 Mars 包使用相对引用。你可以使用

python ./ci/importcheck.py

来检查你的代码是否满足要求。

编译文档#

Mars 使用 sphinx 编译文档。在编译 HTML 格式的文档前，你需要使用下面的命令安装必要的依赖包

pip install -r docs/requirements-doc.txt
cd docs
make html

编译完成的 HTML 文档位于 docs/build/html 目录下。

当你希望创建 Mars 文档的翻译，你可以在 Makefile 的 I18NSPHINXLANGS 变量末尾追加新的 -l <locale>，目前仅支持简体中文。此后，执行下面的命令为文档生成翻译文件（*.po），生成后的文件位于 docs/source/locale/<locale>/LC_MESSAGES 下：

cd docs
make gettext

此后你可以在 po 文件中将 Mars 文档翻译成你所需的语言。注意当你再次运行 make gettext，翻译后的文字将被转为固定宽度文字。对于中文译者，为达到该效果，需要安装 jieba 分词包。

在完成翻译后，你可以执行

cd docs
# change LANG into the language you want to build
make -e SPHINXOPTS="-D language='LANG'" html

以使用你刚才翻译的语言编译文档。