# 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. 術語表