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. Mailing-list

There is a public mailing-list that you can e-mail at numba-users@anaconda.com. If you have any questions about contributing to numba-scipy, it is ok to ask them on this mailing-list. You can subscribe and read the archives on Google Groups.

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 master 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 master 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