mirror of
https://github.com/wassname/scikit-image.git
synced 2026-07-02 01:55:39 +08:00
Tweak Sphinx rendering of contribution page
This commit is contained in:
Tony S Yu
+90
-72
@@ -5,35 +5,50 @@ 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, ``upstream`` refers to the ``scikit-image`` repository and
|
||||
``origin`` to your personal fork.
|
||||
* 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``)
|
||||
* 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.
|
||||
* 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``
|
||||
@@ -41,79 +56,82 @@ For a more detailed discussion, read these :doc:`detailed documents
|
||||
|
||||
.. note::
|
||||
|
||||
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::
|
||||
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.
|
||||
|
||||
git checkout master
|
||||
git pull upstream master
|
||||
git checkout transform-speedups
|
||||
git rebase master
|
||||
|
||||
If any conflicts occur, fix the according files and continue::
|
||||
Divergence between ``upstream master`` and your feature branch
|
||||
..............................................................
|
||||
|
||||
git add conflict-file1 conflict-file2
|
||||
git rebase --continue
|
||||
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::
|
||||
|
||||
However, you should only rebase your own branches and must generally not
|
||||
rebase any branch which you collaborate on with someone else.
|
||||
git checkout master
|
||||
git pull upstream master
|
||||
git checkout transform-speedups
|
||||
git rebase master
|
||||
|
||||
Finally, you must push your rebased branch::
|
||||
If any conflicts occur, fix the according files and continue::
|
||||
|
||||
git push --force origin transform-speedups
|
||||
git add conflict-file1 conflict-file2
|
||||
git rebase --continue
|
||||
|
||||
(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>`__.)
|
||||
However, you should only rebase your own branches and must generally not
|
||||
rebase any branch which you collaborate on with someone else.
|
||||
|
||||
* 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.
|
||||
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.
|
||||
* 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.
|
||||
* 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 numpy data types instead of strings (``np.uint8`` instead of
|
||||
``"uint8"``).
|
||||
|
||||
* Use the following import conventions::
|
||||
* Use the following import conventions::
|
||||
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
import numpy as np
|
||||
import matplotlib.pyplot as plt
|
||||
|
||||
cimport numpy as cnp # in Cython code
|
||||
cimport numpy as cnp # in Cython code
|
||||
|
||||
* When documenting array parameters, use ``image : (M, N) ndarray``,
|
||||
``image : (M, N, 3) ndarray`` and then refer to ``M`` and ``N`` in the
|
||||
docstring.
|
||||
* 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.::
|
||||
* 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))
|
||||
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 ``Py_ssize_t`` as data type for all indexing, shape and size variables
|
||||
in C/C++ and Cython code.
|
||||
|
||||
Test coverage
|
||||
-------------
|
||||
|
||||
Reference in New Issue
Block a user