mirror of
https://github.com/wassname/scikit-image.git
synced 2026-07-14 11:18:06 +08:00
Added GitHub templates, moved CONTRIBUTING.md to .github
This commit is contained in:
Egor Panfilov
@@ -0,0 +1,301 @@
|
||||
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 the 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 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>`_.
|
||||
@@ -0,0 +1,15 @@
|
||||
## Description
|
||||
[Please provide a general introduction to the issue/proposal.]
|
||||
|
||||
[If reporting a bug, attach the entire traceback from Python.]
|
||||
[If proposing an enhancement/new feature, provide links to related articles, reference examples, etc.]
|
||||
|
||||
|
||||
## Way to reproduce
|
||||
[If reporting a bug, please include the following important information:]
|
||||
- [ ] Code example
|
||||
- [ ] Relevant images (if any)
|
||||
- [ ] Operating system and version
|
||||
- [ ] Python version
|
||||
- [ ] scikit-image version (run `skimage.__version__`)
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
## Description
|
||||
[Tell us about your new feature, improvement, or fix! If relevant, please supplement the PR with images.]
|
||||
|
||||
|
||||
## Checklist
|
||||
[It's fine to submit PRs which are a work in progress! But before they are merged, all PRs should provide:]
|
||||
- [ ] Clean style in [the spirit of PEP8](https://www.python.org/dev/peps/pep-0008/)
|
||||
- [ ] [Docstrings for all functions](https://github.com/numpy/numpy/blob/master/doc/example.py)
|
||||
- [ ] Gallery example in `./doc/examples` (new features only)
|
||||
- [ ] Unit tests
|
||||
|
||||
[For detailed information on these and other aspects see [scikit-image contribution guidelines](http://scikit-image.org/docs/dev/contribute.html)]
|
||||
|
||||
|
||||
## References
|
||||
[If this is a bug-fix or enhancement, it closes issue # ]
|
||||
[If this is a new feature, it implements the following paper: ]
|
||||
|
||||
Reference in New Issue
Block a user