From f4263556c4e855b0b2b0dab24a0557c550682108 Mon Sep 17 00:00:00 2001 From: Stefan van der Walt Date: Mon, 20 Aug 2012 10:43:12 -0700 Subject: [PATCH 1/2] DOC: Update development guidelines. --- DEVELOPMENT.txt | 40 +++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/DEVELOPMENT.txt b/DEVELOPMENT.txt index 4b42cf37..3f10276d 100644 --- a/DEVELOPMENT.txt +++ b/DEVELOPMENT.txt @@ -9,32 +9,36 @@ Development process 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 'your_name-transform-speedups'. + such as 'transform-speedups'. * Commit locally as you progress. * Push your changes back to github and create a pull request by clicking "request pull" in GitHub. * Optionally, mail the mailing list, explaining your changes. +.. 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. + + (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 -.. note:: - - Do *not* merge the main branch into yours. You may rebase, - as long as you are `aware of its dangers `_ - (also see `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". - 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. If possible, also add a section to the user guide. + 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 @@ -42,6 +46,20 @@ Guidelines you get no response to your pull request. * Examples in the gallery should have a maximum figure width of 8 inches. +Stylistic Guidelines +```````````````````` + * Use numpy data types instead of strings (``np.uint8`` instead of + ``"uint8"``). + + * Use the following import conventions:: + + import numpy as np + import matplotlib.pyplot as plt + + cimport numpy as cnp # in Cython code + + * Set up your editor to remove trailing whitespace. + Test coverage ````````````` Tests for a module should ideally cover all code in that module, From e5bbceac1f88bbbf83a24d64b5646ecca4fb575f Mon Sep 17 00:00:00 2001 From: Stefan van der Walt Date: Mon, 20 Aug 2012 11:19:58 -0700 Subject: [PATCH 2/2] DOC: More coding conventions. --- DEVELOPMENT.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/DEVELOPMENT.txt b/DEVELOPMENT.txt index 3f10276d..e205af85 100644 --- a/DEVELOPMENT.txt +++ b/DEVELOPMENT.txt @@ -58,7 +58,19 @@ Stylistic Guidelines 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. * Set up your editor to remove trailing whitespace. + * 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. + * 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)) Test coverage `````````````