# 7.1。贡献给 Numba
> 原文： [http://numba.pydata.org/numba-doc/latest/developer/contributing.html](http://numba.pydata.org/numba-doc/latest/developer/contributing.html)
我们欢迎那些想要为 Numba 做出贡献的人，无论大小！甚至鼓励简单的文档改进。如果您有疑问，请不要犹豫（见下文）。
## 7.1.1。通讯
### 7.1.1.1。邮件列表
我们有一个公共邮件列表，您可以通过 [numba-users@anaconda.com](/cdn-cgi/l/email-protection#87e9f2eae5e6aaf2f4e2f5f4a1a4b4b0bca1a4b2b5bca1a4b3bfbce6e9e6e4e8e9e3e6a1a4b3b1bce4e8ea) 发送电子邮件。如果您对 Numba 有任何疑问，可以在此邮件列表中询问他们。您可以在 [Google 网上论坛](https://groups.google.com/a/continuum.io/forum/#!forum/numba-users)上订阅和阅读档案，还有一个允许 NNTP 访问的 [Gmane 镜像](http://news.gmane.org/gmane.comp.python.numba.user)。
### 7.1.1.2。实时聊天
Numba 使用 Gitter 进行公共实时聊天。为了帮助提高信噪比，我们有两个渠道：
* [numba / numba](https://gitter.im/numba/numba) ：Numba 将军的讨论，问题和调试帮助。
* [numba / numba-dev](https://gitter.im/numba/numba-dev) ：关于 PR，计划，发布协调等的讨论
这两个频道都是公开的，但我们可能会要求关于 numba-dev 的讨论转移到 numba 频道。这只是为了确保核心开发人员能够轻松跟上 numba-dev。
请注意，Github 问题跟踪器是报告错误的最佳位置。聊天中的错误报告很难跟踪，可能会丢失。
### 7.1.1.3。每周会议
Numba 核心开发人员每周都会召开视频会议，讨论路线图，功能规划和未解决的问题。这些会议仅限邀请，但会有几分钟的时间，并会发布到 [Numba wiki](https://github.com/numba/numba/wiki/Meeting-Minutes) 。
### 7.1.1.4。错误跟踪器
我们使用 [Github 问题跟踪器](https://github.com/numba/numba/issues)来跟踪错误报告和功能请求。如果您报告问题，请提供具体信息：
* 你想做什么;
* 您拥有哪个操作系统以及您正在运行的 Numba 版本;
* Numba 如何行为不端，例如完整的错误追溯，或您获得的意外结果;
* 尽可能使用一个代码片段，可以完全复制您的问题。
## 7.1.2。设置
如果您想贡献，我们建议您分配我们的 [Github 存储库](https://github.com/numba/numba)，然后创建一个代表您工作的分支。当您的工作准备就绪时，您应该将其作为来自 Github 界面的拉取请求提交。
如果需要，即使您尚未完成工作，也可以提交拉取请求。这对于收集反馈或强调您对[持续集成](#travis-ci)平台的更改非常有用。在这种情况下，请将`[WIP]`添加到您的拉取请求标题中。
### 7.1.2.1。构建环境
Numba 有许多依赖项（主要是 [NumPy](http://www.numpy.org/) 和 [llvmlite](https://github.com/numba/llvmlite) ），具有非平凡的构建指令。除非您想自己构建这些依赖项，否则我们建议您使用 [conda](http://conda.pydata.org/miniconda.html) 创建专用开发环境并在那里安装这些依赖项的预编译版本。
首先添加 Anaconda Cloud `numba`通道，以获得 llvmlite 库的开发版本：
```py
$ conda config --add channels numba
```
然后创建一个具有正确依赖关系的环境：
```py
$ conda create -n numbaenv python=3.6 llvmlite numpy scipy jinja2 cffi
```
注意
这将安装基于 Python 3.6 的环境，但您当然可以选择 Numba 支持的另一个版本。要测试其他功能，您可能还需要安装`tbb`和/或`llvm-openmp`和`intel-openmp`。
要激活当前 shell 会话的环境：
```py
$ conda activate numbaenv
```
注意
这些说明适用于标准 Linux shell。您可能需要针对其他平台进行调整。
激活环境后，您将拥有一个具有所需依赖项的专用 Python：
```py
$ 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：
```py
$ 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`](https://docs.python.org/3/library/unittest.html#module-unittest "(in Python v3.7)") 框架编写。
可以通过`python -m numba.runtests`执行测试。如果您从源结帐中运行 Numba，则可以键入`./runtests.py`作为快捷方式。支持各种选项以影响测试运行和报告。通过`-h`或`--help`以了解这些选项。例子：
* 列出所有可用的测试：
```py
$ python -m numba.runtests -l
```
* 列出来自特定（子）套件的测试：
```py
$ python -m numba.runtests -l numba.tests.test_usecases
```
* 运行这些测试：
```py
$ python -m numba.runtests numba.tests.test_usecases
```
* 使用多个子流程并行运行所有测试：
```py
$ python -m numba.runtests -m
```
* 有关所有选项的详细列表：
```py
$ python -m numba.runtests -h
```
numba 测试套件可能需要很长时间才能完成。当您想避免漫长的等待时，首先使用以下测试运行器选项关注失败的测试是有用的：
* 添加`--failed-first`选项以捕获失败的测试列表并首先重新执行它们：
```py
$ python -m numba.runtests --failed-first -mvb
```
* `--last-failed`选项与`--failed-first`一起使用，仅执行以前失败的测试：
```py
$ 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**](https://www.python.org/dev/peps/pep-0008)。我们的 C 代码没有明确定义的编码风格（关注 [**PEP 7**](https://www.python.org/dev/peps/pep-0007)会不会很好？）。代码和文档通常应该在 80 列内，以便使用所有现有工具（例如代码审查 UI）获得最大可读性。
### 7.1.3.3。稳定性
存储库的`master`分支应始终保持稳定。这转化为测试套件在所有支持的平台上通过而没有错误的事实（见下文）。这也意味着拉取请求还需要在合并之前通过测试套件。
### 7.1.3.4。平台支持
每个对主分支的提交都会在 Numba 支持的所有平台上自动进行测试。这包括 ARMv7，ARMv8，POWER8，以及 AMD 和 NVIDIA GPU。然而，构建系统是 Anaconda 的内部系统，因此我们还使用 [Travis CI](https://travis-ci.org/numba/numba) 和 [AppVeyor](https://ci.appveyor.com/project/seibert/numba-j46mi) 为服务支持的尽可能多的组合提供公共持续集成信息。 Travis CI 自动测试 OS X 和 Linux 上的所有拉取请求，以及不同 Python 和 NumPy 版本的样本。如果您在不熟悉的平台上发现问题，请随时在拉取请求中寻求帮助。 Numba 核心开发人员可以帮助诊断跨平台兼容性问题。
## 7.1.4。文件
Numba 文档分为两个存储库：
* 该文档位于 [Numba 存储库](https://github.com/numba/numba)内的`docs`目录中。
* [Numba 主页](http://numba.pydata.org)的来源位于 [https://github.com/numba/numba-webpage](https://github.com/numba/numba-webpage) 的单独存储库中
### 7.1.4.1。主要文件
该文档位于 [Numba 存储库](https://github.com/numba/numba)的`docs`目录下。它由 [Sphinx](http://sphinx-doc.org/) 构建，可以使用 conda 或 pip。
要构建文档，您需要引导主题：
```py
$ pip install sphinx_bootstrap_theme
```
您可以在`docs/source/`下编辑源文件，之后您可以构建并检查文档：
```py
$ make html
$ open _build/html/index.html
```
核心开发人员可以使用`docs`下的`gh-pages.py`脚本将此文档上传到 Numba 网站 [http://numba.pydata.org](http://numba.pydata.org) ：
```py
$ 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](http://numba.pydata.org) 上的 Numba 主页可以从这里获取： [https://github.com/numba/numba-webpage](https://github.com/numba/numba-webpage)
将文档推送到新版本后，核心开发人员将需要更新网站。一些值得注意的文件：
* `index.rst`＃更新主页面
* `_templates/sidebar_versions.html`＃更新侧栏链接
* `doc.rst`＃为 numba docs 添加新版本后更新
* `download.rst`将新的 numba 版本上传到 pypi 后的＃Updata
更新后运行：
```py
$ make html
```
并查看`_build/html/index.html`。要推送更新到网站：
```py
$ python _scripts/gh-pages.py
```
然后验证`gh-pages`目录下的存储库。确保`CNAME`文件存在且包含`numba.pydata.org`的单行。最后，使用`git push`更新网站。
- 1. 用户手册
- 1.1。 Numba 的约 5 分钟指南
- 1.2。概述
- 1.3。安装
- 1.4。使用@jit 编译 Python 代码
- 1.5。使用@generated_jit 进行灵活的专业化
- 1.6。创建 Numpy 通用函数
- 1.7。用@jitclass 编译 python 类
- 1.8。使用@cfunc 创建 C 回调
- 1.9。提前编译代码
- 1.10。使用@jit 自动并行化
- 1.11。使用@stencil装饰器
- 1.12。从 JIT 代码 中回调到 Python 解释器
- 1.13。性能提示
- 1.14。线程层
- 1.15。故障排除和提示
- 1.16。常见问题
- 1.17。示例
- 1.18。会谈和教程
- 2. 参考手册
- 2.1。类型和签名
- 2.2。即时编译
- 2.3。提前编译
- 2.4。公用事业
- 2.5。环境变量
- 2.6。支持的 Python 功能
- 2.7。支持的 NumPy 功能
- 2.8。与 Python 语义的偏差
- 2.9。浮点陷阱
- 2.10。 Python 2.7 寿命终止计划
- 3. 用于 CUDA GPU 的 Numba
- 3.1。概述
- 3.2。编写 CUDA 内核
- 3.3。内存管理
- 3.4。编写设备功能
- 3.5。 CUDA Python 中支持的 Python 功能
- 3.6。支持的原子操作
- 3.7。随机数生成
- 3.8。设备管理
- 3.10。示例
- 3.11。使用 CUDA 模拟器 调试 CUDA Python
- 3.12。 GPU 减少
- 3.13。 CUDA Ufuncs 和广义 Ufuncs
- 3.14。共享 CUDA 内存
- 3.15。 CUDA 阵列接口
- 3.16。 CUDA 常见问题
- 4. CUDA Python 参考
- 4.1。 CUDA 主机 API
- 4.2。 CUDA 内核 API
- 4.3。内存管理
- 5. 用于 AMD ROC GPU 的 Numba
- 5.1。概述
- 5.2。编写 HSA 内核
- 5.3。内存管理
- 5.4。编写设备功能
- 5.5。支持的原子操作
- 5.6。代理商
- 5.7。 ROC Ufuncs 和广义 Ufuncs
- 5.8。示例
- 6. 扩展 Numba
- 6.1。高级扩展 API
- 6.2。低级扩展 API
- 6.3。示例：间隔类型
- 7. 开发者手册
- 7.1。贡献给 Numba
- 7.2。 Numba 建筑
- 7.3。多态调度
- 7.4。关于发电机的注意事项
- 7.5。关于 Numba Runtime 的注意事项
- 7.6。使用 Numba Rewrite Pass 获得乐趣和优化
- 7.7。实时变量分析
- 7.8。上市
- 7.9。模板注释
- 7.10。关于自定义管道的注意事项
- 7.11。环境对象
- 7.12。哈希 的注意事项
- 7.13。 Numba 项目路线图
- 8. Numba 增强建议
- 9. 术语表