How to contribute to skimage

Developing Open Source is great fun! Join us on the scikit-image mailing list and tell us which of the following challenges you’d like to solve.

Development process

Here’s the long and short of it:

  • Go to https://github.com/scikit-image/scikit-image and follow the instructions on making your own fork.
  • Create a new branch for the feature you want to work on. Since the branch name will appear in the merge message, use a sensible name such as ‘transform-speedups’.
  • Commit locally as you progress.
  • Push your changes back to GitHub and create a Pull Request by clicking ‘Pull Request’ in GitHub.
  • Optionally, post on the mailing list to explain your changes.

Read these detailed documents on how to use Git with scikit-image (http://scikit-image.org/docs/dev/gitwash/index.html).

Note

Do not merge the main branch into yours. If GitHub indicates that the Pull Request can no longer be merged automatically, rebase onto master.

(If you are curious, here’s a further discussion on the dangers of rebasing. Also see this LWN article.)

  • To reviewers: add a short explanation of what a branch did to the merge message or, if closing a bug, add “Closes gh-XXXX”.

You may also read this summary by Fernando Perez of the IPython project on how they manage to keep review overhead to a minimum:

http://mail.scipy.org/pipermail/ipython-dev/2010-October/006746.html

Guidelines

  • All code should have tests (see test coverage below for more details).
  • All code should be documented, to the same standard as NumPy and SciPy. For new functionality, always add an example to the gallery.
  • Follow the Python PEPs where possible.
  • No major changes should be committed without review. Ask on the mailing list if you get no response to your pull request.
  • Examples in the gallery should have a maximum figure width of 8 inches.

Stylistic Guidelines

  • Use numpy data types instead of strings (np.uint8 instead of "uint8").

  • Use the following import conventions:

    import numpy as np
    import matplotlib.pyplot as plt
    
    cimport numpy as cnp # in Cython code
  • When documenting array parameters, use image : (M, N) ndarray, image : (M, N, 3) ndarray and then refer to M and N in the docstring.

  • Set up your editor to remove trailing whitespace. Follow PEP08. Check code with pyflakes / flake8.

  • If a function name, say segment(...), has the same name as the file in which it is implemented, name that file _segment.py so that it can still be imported. All Cython files start with an underscore, e.g. _some_module.pyx.

  • Functions should support all input image dtypes. Use utility functions such as img_as_float to help convert to an appropriate type. The output format can be whatever is most efficient. This allows us to string together several functions into a pipeline, e.g.:

    hough(canny(my_image))
    
  • Use Py_ssize_t as data type for all indexing, shape and size variables in C/C++ and Cython code.

Test coverage

Tests for a module should ideally cover all code in that module, i.e., statement coverage should be at 100%.

To measure the test coverage, install coverage.py (using easy_install coverage) and then run:

$ make coverage

This will print a report with one line for each file in skimage, detailing the test coverage:

Name                                             Stmts   Exec  Cover   Missing
------------------------------------------------------------------------------
skimage/color/colorconv                             77     77   100%
skimage/filter/__init__                              1      1   100%
...