为Mars贡献#

Mars是一个在Apache License 2.0下发布的开源项目。我们欢迎并感谢您的贡献。以下是一些您可能会发现有用的指南，当您想对Mars进行一些更改时。

一般指南#

Mars 在 Github 上托管和维护其代码。我们提供一个通用指南用于打开问题和拉取请求。

设置开发环境#

除非您想在Windows下开发或调试Mars，否则强烈建议在MacOS或Linux下开发Mars，在那里您可以测试Mars的所有功能。下面列出的步骤适用于MacOS和Linux。

在Conda中安装#

建议使用conda开发Mars。当您想要安装Mars进行开发时，请使用以下步骤创建环境并在其中安装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，您可以将 --user 添加到 pip install 命令中。

验证#

安装Mars后，您可以通过运行以下命令检查Mars是否正确安装

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

如果该命令正确输出您的 Mars 版本，则 Mars 已正确安装。

重建 Cython 代码#

Mars 使用 Cython 来加速其部分代码。在您更改 Cython 源代码后，您需要通过在 Mars 项目的根目录下执行以下命令将其编译为二进制文件：

python setup.py build_ext -i

重建前端代码#

Mars使用React来构建其前端。您需要安装nodejs以从源代码构建它。安装所有依赖项后，只需使用以下命令构建您的前端代码：

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使用 black 来强制执行Python代码风格。只需运行以下命令即可自动格式化您的代码风格：

black mars

我们还要求所有Mars模块的代码中使用相对导入。使用

python ./ci/importcheck.py

检查您的代码是否符合要求。

构建文档#

Mars使用sphinx来构建文档。您需要使用下面的命令安装必要的包，以安装这些依赖项并将您的文档构建为HTML。

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

生成的文档位于 docs/build/html 目录中。

当您想要创建Mars文档的翻译时，可以在I18NSPHINXLANGS变量后附加-l。目前仅支持简体中文。之后，运行下面的命令以生成文档的可移植文件（*.po），这些文件位于docs/source/locale//LC_MESSAGES：

cd docs
make gettext

之后，您可以将Mars文档翻译成您的语言。请注意，当您再次运行 make gettext 时，翻译将被打断为固定宽度文本。对于中文翻译者，您需要安装 jieba 来获得此效果。

完成翻译后，您可以运行

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

以您刚翻译的语言构建文档。