From fa72a20cdccbf91e2014744a58fece4db6332552 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Sch=C3=B6nberger?= Date: Sun, 16 Jun 2013 21:18:39 +0200 Subject: [PATCH 1/6] Refactor contribution workflow --- CONTRIBUTING.txt | 41 +++++++++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.txt b/CONTRIBUTING.txt index ca3f54ab..03e8deb6 100644 --- a/CONTRIBUTING.txt +++ b/CONTRIBUTING.txt @@ -9,19 +9,17 @@ Here's the long and short of it: `_ 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. + ``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 forked. 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 + (``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`` @@ -29,10 +27,10 @@ Here's the long and short of it: 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. + * 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. @@ -43,11 +41,22 @@ For a more detailed discussion, read these :doc:`detailed documents .. note:: - Do *not* ever merge the main branch into yours. If GitHub indicates that + 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:: - git fetch origin/master - git rebase origin/master + git checkout master + git pull upstream master + git checkout your-branch + git rebase master + + If any conflicts occur, fix the according files and continue:: + + git add conflict-file1 conflict-file2 + git rebase --continue + + Finally, you must push your rebased branch:: + + git push -f (If you are curious, here's a further discussion on the `dangers of rebasing `__. Also From b5fbca3f00d2697f63690179f8b91891217a69e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Sch=C3=B6nberger?= Date: Sun, 16 Jun 2013 21:26:18 +0200 Subject: [PATCH 2/6] Change branch name for consistency across guidelines --- CONTRIBUTING.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.txt b/CONTRIBUTING.txt index 03e8deb6..a1d3b666 100644 --- a/CONTRIBUTING.txt +++ b/CONTRIBUTING.txt @@ -46,7 +46,7 @@ For a more detailed discussion, read these :doc:`detailed documents git checkout master git pull upstream master - git checkout your-branch + git checkout transform-speedups git rebase master If any conflicts occur, fix the according files and continue:: @@ -56,7 +56,7 @@ For a more detailed discussion, read these :doc:`detailed documents Finally, you must push your rebased branch:: - git push -f + git push -f origin transform-speedups (If you are curious, here's a further discussion on the `dangers of rebasing `__. Also From 1eb841d116d66f53a22c3695f877df0a8144c52a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Sch=C3=B6nberger?= Date: Mon, 17 Jun 2013 16:16:13 +0200 Subject: [PATCH 3/6] Fix typo --- CONTRIBUTING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.txt b/CONTRIBUTING.txt index a1d3b666..69ae82e2 100644 --- a/CONTRIBUTING.txt +++ b/CONTRIBUTING.txt @@ -13,7 +13,7 @@ Here's the long and short of it: * 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 forked. + ``origin`` to your personal fork. 2. Develop your contribution: From 8e4c11cf489419911bb1ae36909e4a33eb41a9ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Sch=C3=B6nberger?= Date: Mon, 17 Jun 2013 16:39:35 +0200 Subject: [PATCH 4/6] Add additional advice about rebasing --- CONTRIBUTING.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.txt b/CONTRIBUTING.txt index 69ae82e2..7275cc30 100644 --- a/CONTRIBUTING.txt +++ b/CONTRIBUTING.txt @@ -41,8 +41,9 @@ 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:: + 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 @@ -54,6 +55,9 @@ For a more detailed discussion, read these :doc:`detailed documents 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 -f origin transform-speedups From 752e860d3de09946033498372ef22de827c51a7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Sch=C3=B6nberger?= Date: Mon, 17 Jun 2013 16:40:28 +0200 Subject: [PATCH 5/6] Use long parameter version --force rather than -f --- CONTRIBUTING.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.txt b/CONTRIBUTING.txt index 7275cc30..73978b10 100644 --- a/CONTRIBUTING.txt +++ b/CONTRIBUTING.txt @@ -60,7 +60,7 @@ For a more detailed discussion, read these :doc:`detailed documents Finally, you must push your rebased branch:: - git push -f origin transform-speedups + git push --force origin transform-speedups (If you are curious, here's a further discussion on the `dangers of rebasing `__. Also From 5efe571bbdbf7589352d507fd7a6e92d1f4273ac Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Wed, 19 Jun 2013 21:24:47 -0500 Subject: [PATCH 6/6] 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 -------------