mirror of
https://github.com/wassname/scikit-image.git
synced 2026-07-19 11:27:45 +08:00
199 lines
6.7 KiB
Plaintext
199 lines
6.7 KiB
Plaintext
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>`_).
|
|
|
|
4. Review process:
|
|
|
|
* Reviewers (the other developers and interested community members) will
|
|
write inline and/or general comments on your Pull Request (PR) to improve
|
|
the implementation and the documentation. Everyone has their code reviewed
|
|
in the same manner, it should not discourage you to contribute and it is
|
|
actually a chance to improve your coding skills. Code review ensures high
|
|
quality code, homogeneous style and optimal performance.
|
|
|
|
* To update your pull request, make your changes on your local repository
|
|
and commit. As soon as those changes are pushed up to the same branch as
|
|
before, the pull request will be automatically updated.
|
|
|
|
* `Travis-CI <http://travis-ci.org/>`__, a continuous integration service
|
|
is triggered after each Pull Request update, to build the code, run the
|
|
unittests, measure the code coverage and check the coding style (PEP8) of
|
|
your branch.
|
|
|
|
.. 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>`_.
|