How to contribute to skimage¶

Development process¶

Here’s the long and short of it:

1. If you are a first-time contributor:

   • Go to https://github.com/scikit-image/scikit-image and click the “fork” button to create your own copy of the project.

   • Clone the project to your local computer:

     git clone git@github.com:your-username/scikit-image.git
     

   • Add upstream repository:

     git remote add upstream git@github.com:scikit-image/scikit-image.git
     

   • Now, you have remote repositories named:

     • upstream, which refers to the scikit-image repository
     • origin, which refers to your personal fork

2. Develop your contribution:

   • Pull the latest changes from upstream:

     git checkout master
     git pull upstream master
     

   • Create a 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’:

     git checkout -b transform-speedups
     

   • Commit locally as you progress (git add and git commit)

3. To submit your contribution:

   • Push your changes back to your fork on GitHub:

     git push origin transform-speedups
     

   • Go to GitHub. The new branch will show up with a Pull Request button - click it.

   • If you want, post on the mailing list to explain your changes or to ask for review.

For a more detailed discussion, read these detailed documents on how to use Git with scikit-image (http://scikit-image.org/docs/dev/gitwash/index.html).

git checkout master
git pull upstream master
git checkout transform-speedups
git rebase master

git add conflict-file1 conflict-file2
git rebase --continue

git push --force origin transform-speedups

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.
• No changes should be committed without review. Ask on the mailing list if you get no response to your pull request. Never merge your own pull request.
• Examples in the gallery should have a maximum figure width of 8 inches.

Stylistic Guidelines¶

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

• 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 and then refer to M and N in the docstring, if necessary.

• 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%
...

Activate Travis-CI for your fork (optional)¶

Travis-CI checks all unittests in the project to prevent breakage.

Before sending a pull request, you may want to check that Travis-CI successfully passes all tests. To do so,

• Go to Travis-CI and follow the Sign In link at the top
• Go to your profile page and switch on your

scikit-image fork

It corresponds to steps one and two in Travis-CI documentation (Step three is already done in scikit-image).

Thus, as soon as you push your code to your fork, it will trigger Travis-CI, and you will receive an email notification when the process is done.

Bugs¶

Please report bugs on GitHub.