diff --git a/CONTRIBUTING.txt b/CONTRIBUTING.txt index ca3f54ab..38ec8e4b 100644 --- a/CONTRIBUTING.txt +++ b/CONTRIBUTING.txt @@ -5,37 +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 - `_ 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:john_doe/scikit-image.git`` - * Add origin and user branches: - ``git remote rm origin`` - ``git remote add origin git@github.com:scikit-image/scikit-image.git`` - ``git remote add john_doe git@github.com:john_doe/scikit-image.git`` - Now, ``origin`` refers to the ``scikit-image`` repository and - ``john_doe`` (your username) to yours. + * Go to `https://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 origin 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 GitHub: - ``git push john_doe 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 - `_ 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 + `_ to explain your changes or + to ask for review. For a more detailed discussion, read these :doc:`detailed documents ` on how to use Git with ``scikit-image`` @@ -43,64 +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 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 fetch origin/master - git rebase origin/master - (If you are curious, here's a further discussion on - the `dangers of rebasing `__. Also - see this `LWN article `__.) +Divergence between ``upstream master`` and your feature branch +.............................................................. -* 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. +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 `__. +Also see this `LWN article `__.) Guidelines ---------- - * All code should have tests (see `test coverage`_ below for more details). - * All code should be documented, to the same - `standard `_ - 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 `_ 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 `_ + 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 `_ 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 - `__. Check code with pyflakes / flake8. +* Set up your editor to remove trailing whitespace. Follow `PEP08 + `__. 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 -------------