3. Contributing to numba-scipy¶
Contributions to numba-scipy are always welcomed! Even simple documentation improvements are encouraged. If you have questions, don’t hesitate to ask them (see below).
3.1. Communication¶
3.1.1. Contact¶
The Numba community uses Discourse for asking questions and having discussions about numba-scipy. There are various categories available and it can be reached at: numba.discourse.group. There is a category for numba-scipy.
3.1.2. Real-time Chat¶
numba-scipy uses Gitter for public real-time chat. To help improve the signal-to-noise ratio, there are two channels:
numba/numba: General discussion, questions, and debugging help.
numba/numba-dev: Discussion of PRs, planning, release coordination, etc.
Both channels are public.
Note that the Github issue tracker is the best place to report bugs. Bug reports in chat are difficult to track and likely to be lost.
3.1.3. Bug tracker¶
The Github issue tracker is used to track both bug reports and feature requests.
3.2. Getting set up¶
If you want to contribute, it’s best to fork the Github repository, then create a branch representing your work. When your work is ready, you should submit it as a pull request from the Github interface.
If you want, you can submit a pull request even when you haven’t finished
working. This can be useful to gather feedback, or to stress your changes
against the continuous integration platform. In this
case, please prepend [WIP]
to your pull request’s title.
3.2.1. Build environment¶
numba-scipy has a number of dependencies (mostly Numba and SciPy). Unless you want to build those dependencies yourself, it’s recommended you use conda to create a dedicated development environment and install pre-compiled versions of those dependencies there.
First add the Anaconda Cloud numba
channel so as to get development builds
of the numba library:
$ conda config --add channels numba
Then create an environment with the right dependencies:
$ conda create -n numba-scipy python=3.7 scipy numba
Note
This installs an environment based on Python 3.7, but you can of course choose another version supported by Numba.
To activate the environment for the current shell session:
$ conda activate numba-scipy
Note
These instructions are for a standard Linux shell. You may need to adapt them for other platforms.
Once the environment is activated, you have a dedicated Python with the required dependencies.
3.2.2. Building numba-scipy¶
For a convenient development workflow, it’s recommended that you build numba-scipy inside its source checkout:
$ git clone git://github.com/numba/numba-scipy.git
$ cd numba-scipy
$ python setup.py develop
3.2.3. Running tests¶
numba-scipy is validated using a test suite comprised of various kind of tests
(unit tests, functional tests). The test suite is written using the
standard unittest
framework and rely on pytest
for execution. The
pytest
package will need installing to run the tests, using conda
this
can be achieved by:
$ conda install pytest
The tests can then be executed via python -m pytest
.
3.3. Development rules¶
3.3.1. Code reviews¶
Any non-trivial change should go through a code review by one or several of the core developers. The recommended process is to submit a pull request on github.
A code review should try to assess the following criteria:
general design and correctness
code structure and maintainability
coding conventions
docstrings, comments
test coverage
3.3.2. Coding conventions¶
All Python code should follow PEP 8. Code and documentation should generally fit within 80 columns, for maximum readability with all existing tools (such as code review UIs).
3.3.3. Stability¶
The repository’s main
branch is expected to be stable at all times.
This translates into the fact that the test suite passes without errors
on all supported platforms (see below). This also means that a pull request
also needs to pass the test suite before it is merged in.
3.3.4. Platform support¶
Every commit to the main
branch is automatically tested on a selection of
platforms. Azure is used to to
provide public continuous integration information for as many combinations as
can be supported by the service. If you see problems on platforms with which you
are unfamiliar, feel free to ask for help in your pull request. The numba-scipy
core developers can help diagnose cross-platform compatibility issues.
3.3.5. Documentation¶
This documentation is under the docs
directory of the
numba-scipy repository.
It is built with Sphinx, which is available
using conda or pip.
To build the documentation, you need the bootstrap theme:
$ pip install sphinx_bootstrap_theme
You can edit the source files under docs/source/
, after which you can
build and check the documentation:
$ make html
$ open _build/html/index.html