7.1。貢獻給 Numba · Numba 0.44 中文文檔

# 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`更新網站。