mirror of
https://github.com/wassname/scikit-image.git
synced 2026-06-27 18:25:32 +08:00
Joshua Warner
306 lines
10 KiB
Plaintext
306 lines
10 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 https://github.com/your-username/scikit-image.git
|
|
|
|
* Add the upstream repository::
|
|
|
|
git remote add upstream https://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
|
|
|
|
* Enter your GitHub username and password (repeat contributors or advanced
|
|
users can remove this step by connecting to GitHub with SSH. See detailed
|
|
instructions below if desired).
|
|
|
|
* Go to GitHub. The new branch will show up with a green 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 help
|
|
you improve its implementation, documentation and style. Every single
|
|
developer working on the project has their code reviewed, and we've come
|
|
to see it as friendly conversation from which we all learn and the
|
|
overall code quality benefits. Therefore, please don't let the review
|
|
discourage you from contributing: its only aim is to improve the quality
|
|
of project, not to criticize (we are, after all, very grateful for the
|
|
time you're donating!).
|
|
|
|
* 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 update automatically.
|
|
|
|
* `Travis-CI <http://travis-ci.org/>`__, a continuous integration service,
|
|
is triggered after each Pull Request update to build the code, run unit
|
|
tests, measure code coverage and check coding style (PEP8) of your
|
|
branch. The Travis tests must pass before your PR can be merged. If
|
|
Travis fails, you can find out why by clicking on the "failed" icon (red
|
|
cross) and inspecting the build and test log.
|
|
|
|
* A pull request must be approved by two core team members before merging.
|
|
|
|
5. Document changes
|
|
|
|
If your change introduces any API modifications, please update
|
|
``doc/source/api_changes.txt``.
|
|
|
|
If your change introduces a deprecation, add a reminder to ``TODO.txt``
|
|
for the team to remove the deprecated functionality in the future.
|
|
|
|
.. note::
|
|
|
|
To reviewers: if it is not obvious from the PR description, add a short
|
|
explanation of what a branch did to the merge message and, if closing a
|
|
bug, also add "Closes #123" where 123 is the issue 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 <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard>`_ as NumPy and SciPy.
|
|
* For new functionality, always add an example to the gallery.
|
|
* No changes are ever committed without review and approval by two core
|
|
team members. 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
|
|
<http://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
|
|
from scipy import ndimage as ndi
|
|
|
|
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.
|
|
|
|
* Refer to array dimensions as (plane), row, column, not as x, y, z. See
|
|
:ref:`Coordinate conventions <numpy-images-coordinate-conventions>`
|
|
in the user guide for more information.
|
|
|
|
* 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.
|
|
|
|
* Use relative module imports, i.e. ``from .._shared import xyz`` rather than
|
|
``from skimage._shared import xyz``.
|
|
|
|
* Wrap Cython code in a pure Python function, which defines the API. This
|
|
improves compatibility with code introspection tools, which are often not
|
|
aware of Cython code.
|
|
|
|
* For Cython functions, release the GIL whenever possible, using
|
|
``with nogil:``.
|
|
|
|
|
|
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.
|
|
|
|
Every time Travis is triggered, it also calls on `Coveralls
|
|
<http://coveralls.io>`_ to inspect the current test overage.
|
|
|
|
|
|
Building docs
|
|
-------------
|
|
|
|
To build docs, run ``make`` from the ``doc`` directory. ``make help`` lists
|
|
all targets.
|
|
|
|
Requirements
|
|
~~~~~~~~~~~~
|
|
|
|
Sphinx (>= 1.3) and Latex is needed to build doc.
|
|
|
|
**Sphinx:**
|
|
|
|
.. code:: sh
|
|
|
|
pip install sphinx
|
|
|
|
**Latex Ubuntu:**
|
|
|
|
.. code:: sh
|
|
|
|
sudo apt-get install -qq texlive texlive-latex-extra dvipng
|
|
|
|
**Latex Mac:**
|
|
|
|
Install the full `MacTex <http://www.tug.org/mactex/>`__ installation or
|
|
install the smaller
|
|
`BasicTex <http://www.tug.org/mactex/morepackages.html>`__ and add *ucs*
|
|
and *dvipng* packages:
|
|
|
|
.. code:: sh
|
|
|
|
sudo tlmgr install ucs dvipng
|
|
|
|
Fixing Warnings
|
|
~~~~~~~~~~~~~~~
|
|
|
|
- "citation not found: R###" There is probably an underscore after a
|
|
reference in the first line of a docstring (e.g. [1]\_). Use this
|
|
method to find the source file: $ cd doc/build; grep -rin R####
|
|
|
|
- "Duplicate citation R###, other instance in..."" There is probably a
|
|
[2] without a [1] in one of the docstrings
|
|
|
|
- Make sure to use pre-sphinxification paths to images (not the
|
|
\_images directory)
|
|
|
|
Auto-generating dev docs
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This set of instructions was used to create
|
|
scikit-image/tools/deploy-docs.sh
|
|
|
|
- Go to Github account settings -> personal access tokens
|
|
- Create a new token with access rights ``public_repo`` and
|
|
``user:email only``
|
|
- Install the travis command line tool: ``gem install travis``. On OSX,
|
|
you can get gem via ``brew install ruby``.
|
|
- Take then token generated by Github and run
|
|
``travis encrypt GH_TOKEN=<token>`` from inside a scikit-image repo
|
|
- Paste the output into the secure: field of ``.travis.yml``.
|
|
- The decrypted GH\_TOKEN env var will be available for travis scripts
|
|
|
|
https://help.github.com/articles/creating-an-access-token-for-command-line-use/
|
|
http://docs.travis-ci.com/user/encryption-keys/
|
|
|
|
|
|
Bugs
|
|
----
|
|
|
|
Please `report bugs on GitHub <https://github.com/scikit-image/scikit-image/issues>`_.
|