7.1。贡献给 Numba

原文： http://numba.pydata.org/numba-doc/latest/developer/contributing.html

我们欢迎那些想要为 Numba 做出贡献的人，无论大小！甚至鼓励简单的文档改进。如果您有疑问，请不要犹豫（见下文）。

7.1.1。通讯

7.1.1.1。邮件列表

我们有一个公共邮件列表，您可以通过 numba-users@anaconda.com 发送电子邮件。如果您对 Numba 有任何疑问，可以在此邮件列表中询问他们。您可以在 Google 网上论坛上订阅和阅读档案，还有一个允许 NNTP 访问的 Gmane 镜像。

7.1.1.2。实时聊天

Numba 使用 Gitter 进行公共实时聊天。为了帮助提高信噪比，我们有两个渠道：

• numba / numba ：Numba 将军的讨论，问题和调试帮助。
• numba / numba-dev ：关于 PR，计划，发布协调等的讨论

这两个频道都是公开的，但我们可能会要求关于 numba-dev 的讨论转移到 numba 频道。这只是为了确保核心开发人员能够轻松跟上 numba-dev。

请注意，Github 问题跟踪器是报告错误的最佳位置。聊天中的错误报告很难跟踪，可能会丢失。

7.1.1.3。每周会议

Numba 核心开发人员每周都会召开视频会议，讨论路线图，功能规划和未解决的问题。这些会议仅限邀请，但会有几分钟的时间，并会发布到 Numba wiki 。

7.1.1.4。错误跟踪器

我们使用 Github 问题跟踪器来跟踪错误报告和功能请求。如果您报告问题，请提供具体信息：

• 你想做什么;
• 您拥有哪个操作系统以及您正在运行的 Numba 版本;
• Numba 如何行为不端，例如完整的错误追溯，或您获得的意外结果;
• 尽可能使用一个代码片段，可以完全复制您的问题。

7.1.2。设置

如果您想贡献，我们建议您分配我们的 Github 存储库，然后创建一个代表您工作的分支。当您的工作准备就绪时，您应该将其作为来自 Github 界面的拉取请求提交。

如果需要，即使您尚未完成工作，也可以提交拉取请求。这对于收集反馈或强调您对持续集成平台的更改非常有用。在这种情况下，请将[WIP]添加到您的拉取请求标题中。

7.1.2.1。构建环境

Numba 有许多依赖项（主要是 NumPy 和 llvmlite ），具有非平凡的构建指令。除非您想自己构建这些依赖项，否则我们建议您使用 conda 创建专用开发环境并在那里安装这些依赖项的预编译版本。

首先添加 Anaconda Cloud numba通道，以获得 llvmlite 库的开发版本：

$ conda config --add channels numba

然后创建一个具有正确依赖关系的环境：

$ conda create -n numbaenv python=3.6 llvmlite numpy scipy jinja2 cffi

注意

这将安装基于 Python 3.6 的环境，但您当然可以选择 Numba 支持的另一个版本。要测试其他功能，您可能还需要安装tbb和/或llvm-openmp和intel-openmp。

要激活当前 shell 会话的环境：

$ conda activate numbaenv

注意

这些说明适用于标准 Linux shell。您可能需要针对其他平台进行调整。

激活环境后，您将拥有一个具有所需依赖项的专用 Python：

$ python
Python 3.6.6 |Anaconda, Inc.| (default, Jun 28 2018, 11:07:29)
[GCC 4.2.1 Compatible Clang 4.0.1 (tags/RELEASE_401/final)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import llvmlite
>>> llvmlite.__version__
'0.24.0'

7.1.2.2。建筑 Numba

为了方便开发工作流程，我们建议您在其源代码检查中构建 Numba：

$ git clone git://github.com/numba/numba.git
$ cd numba
$ python setup.py build_ext --inplace

这假设您的开发系统上有一个可用的 C 编译器和运行时。每当修改 Numba 源代码树中的 C 文件时，都必须再次运行此命令。

7.1.2.3。运行测试

Numba 使用由各种测试（单元测试，功能测试）组成的测试套件进行验证。测试套件使用标准 unittest 框架编写。

可以通过python -m numba.runtests执行测试。如果您从源结帐中运行 Numba，则可以键入./runtests.py作为快捷方式。支持各种选项以影响测试运行和报告。通过-h或--help以了解这些选项。例子：

• 列出所有可用的测试：

  $ python -m numba.runtests -l

• 列出来自特定（子）套件的测试：

  $ python -m numba.runtests -l numba.tests.test_usecases

• 运行这些测试：

  $ python -m numba.runtests numba.tests.test_usecases

• 使用多个子流程并行运行所有测试：

  $ python -m numba.runtests -m

• 有关所有选项的详细列表：

  $ python -m numba.runtests -h

numba 测试套件可能需要很长时间才能完成。当您想避免漫长的等待时，首先使用以下测试运行器选项关注失败的测试是有用的：

• 添加--failed-first选项以捕获失败的测试列表并首先重新执行它们：

  $ python -m numba.runtests --failed-first -mvb

• --last-failed选项与--failed-first一起使用，仅执行以前失败的测试：

  $ python -m numba.runtests --last-failed -mvb

7.1.3。发展规则

7.1.3.1。代码评论

任何非平凡的变更都应该由一个或几个核心开发人员进行代码审查。建议的过程是在 github 上提交 pull 请求。

代码审查应尝试评估以下标准：

• 一般设计和正确性
• 代码结构和可维护性
• 编码惯例
• docstrings，comments
• 测试覆盖率

7.1.3.2。编码惯例

所有 Python 代码都应该遵循 PEP 8。我们的 C 代码没有明确定义的编码风格（关注 PEP 7会不会很好？）。代码和文档通常应该在 80 列内，以便使用所有现有工具（例如代码审查 UI）获得最大可读性。

7.1.3.3。稳定性

存储库的master分支应始终保持稳定。这转化为测试套件在所有支持的平台上通过而没有错误的事实（见下文）。这也意味着拉取请求还需要在合并之前通过测试套件。

7.1.3.4。平台支持

每个对主分支的提交都会在 Numba 支持的所有平台上自动进行测试。这包括 ARMv7，ARMv8，POWER8，以及 AMD 和 NVIDIA GPU。然而，构建系统是 Anaconda 的内部系统，因此我们还使用 Travis CI 和 AppVeyor 为服务支持的尽可能多的组合提供公共持续集成信息。 Travis CI 自动测试 OS X 和 Linux 上的所有拉取请求，以及不同 Python 和 NumPy 版本的样本。如果您在不熟悉的平台上发现问题，请随时在拉取请求中寻求帮助。 Numba 核心开发人员可以帮助诊断跨平台兼容性问题。

7.1.4。文件

Numba 文档分为两个存储库：

• 该文档位于 Numba 存储库内的docs目录中。
• Numba 主页的来源位于 https://github.com/numba/numba-webpage 的单独存储库中

7.1.4.1。主要文件

该文档位于 Numba 存储库的docs目录下。它由 Sphinx 构建，可以使用 conda 或 pip。

要构建文档，您需要引导主题：

$ pip install sphinx_bootstrap_theme

您可以在docs/source/下编辑源文件，之后您可以构建并检查文档：

$ make html
$ open _build/html/index.html

核心开发人员可以使用docs下的gh-pages.py脚本将此文档上传到 Numba 网站 http://numba.pydata.org ：

$ python gh-pages.py version  # version can be 'dev' or '0.16' etc

然后验证gh-pages目录下的存储库并使用git push。

7.1.4.2。网站主页

http://numba.pydata.org 上的 Numba 主页可以从这里获取： https://github.com/numba/numba-webpage

将文档推送到新版本后，核心开发人员将需要更新网站。一些值得注意的文件：

• index.rst＃更新主页面
• _templates/sidebar_versions.html＃更新侧栏链接
• doc.rst＃为 numba docs 添加新版本后更新
• download.rst将新的 numba 版本上传到 pypi 后的＃Updata

更新后运行：

$ make html

并查看_build/html/index.html。要推送更新到网站：

$ python _scripts/gh-pages.py

然后验证gh-pages目录下的存储库。确保CNAME文件存在且包含numba.pydata.org的单行。最后，使用git push更新网站。