How to submit contributions?

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

How to submit contributions?

Christoph Dalitz
Dear octave pundits,

for a research project, I have recently implemented versions of "deconvwnr"
(Wiener deconvolution) and "deconvlucy" (Richardson-Lucy deconvolution) in Octave,
which are listed as "missing functions" in octave-forge. I have also implemented
a recent regularization method for the Richardson-Lucy deconvolution that is
absent in matlab.

As I would like to submit them, I have some questions:

 a) There is a website for submitting "patches", but there is
    no information about the form of the "patch".
    Is there an example somewhere how to convert an octave *.m file
    implementing a new function into a suitable "patch"?

 b) Where can I find general style information, like how to
    document the functionality and the author date of last change
    in the submission?

 c) Do you only accept functions that reproduce matlab functonality,
    or are other functions also welcome?
    Is strict matlab compatibility a requirement, or may the interface
    (and maybe the functionality) be slightly different?

Thanks,

Christoph

Reply | Threaded
Open this post in threaded view
|

Re: How to submit contributions?

Mike Miller
Hi Christoph,

On Wed, Sep 24, 2014 at 16:05:30 +0200, Christoph Dalitz wrote:

> Dear octave pundits,
>
> for a research project, I have recently implemented versions of "deconvwnr"
> (Wiener deconvolution) and "deconvlucy" (Richardson-Lucy deconvolution) in Octave,
> which are listed as "missing functions" in octave-forge. I have also implemented
> a recent regularization method for the Richardson-Lucy deconvolution that is
> absent in matlab.
>
> As I would like to submit them, I have some questions:
>
>  a) There is a website for submitting "patches", but there is
>     no information about the form of the "patch".
>     Is there an example somewhere how to convert an octave *.m file
>     implementing a new function into a suitable "patch"?

The ideal submission would be in the form of an exported Mercurial
changeset. Since these functions will likely be part of the image
package, you would clone the image package source repository, make
sure the functions have not been implemented yet, add them and commit
them to your clone, and submit the changeset to the patch tracker.

The Octave manual and wiki both have some things to say about working
with Mercurial (which also applies to most Octave Forge packages):

  https://www.gnu.org/software/octave/doc/interpreter/Basics-of-Generating-a-Changeset.html
  http://wiki.octave.org/Mercurial

If the above makes no sense to you, you can always just submit the
m-files as-is to the patch tracker.

>  b) Where can I find general style information, like how to
>     document the functionality and the author date of last change
>     in the submission?

There is no need to document changes in an m-file, our version control
system does that for us.

The Octave manual has some information about coding and documentation style:

  https://www.gnu.org/software/octave/doc/interpreter/Tips-and-Standards.html
  https://www.gnu.org/software/octave/doc/interpreter/Contributing-Guidelines.html

Furthermore, you can get feedback from reviewers on the patch tracker
once you submit your files.

>  c) Do you only accept functions that reproduce matlab functonality,
>     or are other functions also welcome?
>     Is strict matlab compatibility a requirement, or may the interface
>     (and maybe the functionality) be slightly different?

Each Octave Forge package is maintained relatively independently, so
that would be a question primarily for the package maintainer. But in
general, functions which may be generally useful to a wide audience,
fit with the rest of the package, and do not conflict with other
functions are acceptable even if there is no Matlab equivalent.

If you are providing something that does have a Matlab equivalent,
compatibility is desirable.

Hope that helps,

--
mike

Reply | Threaded
Open this post in threaded view
|

Re: How to submit contributions?

Carnë Draug
In reply to this post by Christoph Dalitz
On 24 September 2014 15:05, Christoph Dalitz
<[hidden email]> wrote:

> Dear octave pundits,
>
> for a research project, I have recently implemented versions of "deconvwnr"
> (Wiener deconvolution) and "deconvlucy" (Richardson-Lucy deconvolution) in Octave,
> which are listed as "missing functions" in octave-forge. I have also implemented
> a recent regularization method for the Richardson-Lucy deconvolution that is
> absent in matlab.
>
> As I would like to submit them, I have some questions:
>
>  a) There is a website for submitting "patches", but there is
>     no information about the form of the "patch".
>     Is there an example somewhere how to convert an octave *.m file
>     implementing a new function into a suitable "patch"?

Yes. Even when adding a new a file, you can do it as a changeset. The
instructions on the Octave manual [1] still apply, the only difference
are: 1) you would be doing it on the image package [2] rather than Octave
core, 2) you would add new files "hg add" rather than modify (and don't
forget to add them to the INDEX file at the root of the package or in the
Makefile if they're C++).

>  b) Where can I find general style information, like how to
>     document the functionality and the author date of last change
>     in the submission?

We follow the GNU coding guidelines. If you come from writing code in
Matlab, the main things to look for are:

  * space between parentheses and function names but not variables, e.g.,
  write "foo (bar)" and "var(idx)".  The main reason for this is that () are
  used for both indexing and calling function and this style allow people
  to easily indentify what is what
  * 2 space indentation
  * also indent (and close) the function block
  * don't use general "end", instead use the specific endif, endfor, etc
  * do not comment on the source date and comments of last modification.
  That's the job of the revision control system (mercurial in our case)

>  c) Do you only accept functions that reproduce matlab functonality,
>     or are other functions also welcome?
>     Is strict matlab compatibility a requirement, or may the interface
>     (and maybe the functionality) be slightly different?

There's several different questions here:

1) we aim for strict compatibility although we have a few exceptions (the
behaviour of "cd" for example), so please don't implement something that
already exists in Matlab in a different way.

2) adding new options that don't exist in Matlab. We are much more liberal
on that, although we still don't accept everything. On the specific case of
the image package, the strel class has more shapes, bwmorph() is missing
some operations but has extra ones, and graythresh() has an optional argument
to choose different algorithms.

For example, I think it'd be fine to have the deconvolution functions
accept the OTF as well as the PSF because we can distinguish easily each
case (the first would have imaginary part). Basically, as long they make
sense, and don't look they might cause compatibility issues in the future,
it should be fine.

Carnë

[1] http://www.gnu.org/software/octave/doc/interpreter/Basics-of-Generating-a-Changeset.html#Basics-of-Generating-a-Changeset
[2] http://hg.code.sf.net/p/octave/image