DEVELOPMENT.txt

Development process
-------------------

:doc:`Read this overview <gitwash/index>` of how to use Git with
``skimage``.  Here's the long and short of it:

 * Go to `https://github.com/scikits-image/scikits-image
   <http://github.com/scikits-image/scikits-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 'your_name-transform-speedups'.
 * Commit locally as you progress.
 * Push your changes back to github and create a pull request by
   clicking "request pull" in GitHub.
 * Optionally, mail the mailing list, explaining your changes.

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

.. note::

   Do *not* merge the main branch into yours.  You may rebase,
   as long as you are `aware of its dangers <http://tinyurl.com/lll385>`_
   (also see `LWN article <http://tinyurl.com/nqcbkj>`_).

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

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.  If possible, also add a section to the user guide.
 * Follow the `Python PEPs <http://www.python.org/dev/peps/pep-0008/>`_
   where possible.
 * No major changes should be committed without review.  Ask on the
   `mailing list <http://groups.google.com/group/scikits-image>`_ if
   you get no response to your pull request.
 * Examples in the gallery should have a maximum figure width of 8 inches.

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

Bugs
````
Please `report bugs on Github <https://github.com/scikits-image/scikits-image/issues>`_.