CONTRIBUTING.txt

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
     <http://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
     <http://groups.google.com/group/scikit-image>`_ to explain your changes or
     to ask for review.

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

.. note::

   To reviewers: add a short explanation of what a branch did to the merge
   message and, if closing a bug, also add "Closes gh-123" where 123 is the
   bug number.


Divergence between ``upstream master`` and your feature branch
..............................................................

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

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

If any conflicts occur, fix the according files and continue::

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

However, you should only rebase your own branches and must generally not
rebase any branch which you collaborate on with someone else.

Finally, you must push your rebased branch::

   git push --force origin transform-speedups

(If you are curious, here's a further discussion on the
`dangers of rebasing <http://tinyurl.com/lll385>`__.
Also see this `LWN article <http://tinyurl.com/nqcbkj>`__.)

Guidelines
----------

* All code should have tests (see `test coverage`_ below for more details).
* All code should be documented, to the same
  `standard <http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines>`_
  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 <http://groups.google.com/group/scikit-image>`_ 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
  <www.python.org/dev/peps/pep-0008/>`__.  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 <http://nedbatchelder.com/code/coverage/>`__
(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 <http://travis-ci.org/>`__ and follow the Sign In link at the top

   * Go to your `profile page <https://travis-ci.org/profile>`__ and switch on your
   scikit-image fork

It corresponds to steps one and two in
`Travis-CI documentation <http://about.travis-ci.org/docs/user/getting-started/>`__
(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 <https://github.com/scikit-image/scikit-image/issues>`_.