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).
There is a public mailing-list that you can e-mail at firstname.lastname@example.org. 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.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
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
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
unittest framework and rely on
pytest for execution. The
pytest package will need installing to run the tests, using
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
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).
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.
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