From 5efe571bbdbf7589352d507fd7a6e92d1f4273ac Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Wed, 19 Jun 2013 21:24:47 -0500 Subject: [PATCH] Tweak Sphinx rendering of contribution page --- CONTRIBUTING.txt | 162 ++++++++++++++++++++++++++--------------------- 1 file changed, 90 insertions(+), 72 deletions(-) diff --git a/CONTRIBUTING.txt b/CONTRIBUTING.txt index 73978b10..38ec8e4b 100644 --- a/CONTRIBUTING.txt +++ b/CONTRIBUTING.txt @@ -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 - `_ 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 + `_ 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 - `_ 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`` @@ -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 `__. Also - see this `LWN article `__.) +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 `__. +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 -------------