From 1fb8f3f8baecd9edce47fb8e4e027fae6b5f72cd Mon Sep 17 00:00:00 2001 From: Stefan van der Walt Date: Fri, 19 Apr 2013 13:15:47 +0200 Subject: [PATCH] Refresh contribution guidelines. --- CONTRIBUTING.txt | 71 ++++++++++++++++++++++++++---------------------- 1 file changed, 39 insertions(+), 32 deletions(-) diff --git a/CONTRIBUTING.txt b/CONTRIBUTING.txt index daffe705..b9327b58 100644 --- a/CONTRIBUTING.txt +++ b/CONTRIBUTING.txt @@ -3,36 +3,48 @@ Development process Here's the long and short of it: - * Go to `https://github.com/scikit-image/scikit-image - `_ and follow the - instructions on making your own fork. - * Create a new 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'. - * Commit locally as you progress. - * Push your changes back to GitHub and create a Pull Request by - clicking 'Pull Request' in GitHub. - * Optionally, post on the `mailing list `_ to explain your changes. +1. If you are a first-time contributor: -Read these :doc:`detailed documents ` on how to use Git with -``scikit-image`` (``_). + * Go to `https://github.com/scikit-image/scikit-image + `_ and click the + "fork" button to creat your own copy of the project. + * Clone the project to your local computer: + ``git clone git@github.com:my_github_username/scikit-image.git`` + +2. Develop your contribution: + + * 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 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`` +(``_). .. note:: - Do *not* merge the main branch into yours. If GitHub indicates that the - Pull Request can no longer be merged automatically, rebase onto master. + 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. (If you are curious, here's a further discussion on the `dangers of rebasing `__. Also see this `LWN article `__.) * To reviewers: add a short explanation of what a branch did to the merge - message or, if closing a bug, add "Closes gh-XXXX". - -You may also read this summary by Fernando Perez of the IPython -project on how they manage to keep review overhead to a minimum: - -http://mail.scipy.org/pipermail/ipython-dev/2010-October/006746.html + message and, if closing a bug, also add "Closes gh-123" where 123 is the + bug number. Guidelines ---------- @@ -40,18 +52,21 @@ 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 + as NumPy and SciPy. + * For new functionality, always add an example to the gallery. - * Follow the `Python PEPs `_ - where possible. - * No major changes should be committed without review. Ask on the + * 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. + * Use numpy data types instead of strings (``np.uint8`` instead of ``"uint8"``). @@ -66,14 +81,6 @@ Stylistic Guidelines ``image : (M, N, 3) ndarray`` and then refer to ``M`` and ``N`` in the docstring. - * Set up your editor to remove trailing whitespace. Follow `PEP08 - `__. Check code with pyflakes / flake8. - - * If a function name, say ``segment(...)``, has the same name as the file in - which it is implemented, name that file ``_segment.py`` so that it can still - be imported. All Cython files start with an underscore, e.g. - ``_some_module.pyx``. - * 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