# HG changeset patch # User Jaroslav Hajek # Date 1207813308 -7200 # Node ID 97ab6987bb57f61ddeae00856a58e06864494eac # Parent 446dec9d1de52fc939c45b8184a42c452063410d contributing chapter in Octave's manual diff --git a/doc/interpreter/Makefile.in b/doc/interpreter/Makefile.in --- a/doc/interpreter/Makefile.in +++ b/doc/interpreter/Makefile.in @@ -94,7 +94,7 @@ IMAGES = $(IMAGES_EPS) $(IMAGES_PDF) $(IMAGES_PNG) $(IMAGES_TXT) SUB_SOURCE := arith.txi audio.txi basics.txi bugs.txi \ - container.txi control.txi cp-idx.txi data.txi \ + contrib.txi container.txi control.txi cp-idx.txi data.txi \ debug.txi diffeq.txi dynamic.txi emacs.txi errors.txi eval.txi \ expr.txi finance.txi fn-idx.txi func.txi geometry.txi gpl.txi \ grammar.txi image.txi install.txi interp.txi \ diff --git a/doc/interpreter/contrib.txi b/doc/interpreter/contrib.txi new file mode 100644 --- /dev/null +++ b/doc/interpreter/contrib.txi @@ -0,0 +1,217 @@ address@hidden Copyright (C) 2008 Jaroslav Hajek address@hidden address@hidden This file is part of Octave. address@hidden address@hidden Octave is free software; you can redistribute it and/or modify it address@hidden under the terms of the GNU General Public License as published by the address@hidden Free Software Foundation; either version 3 of the License, or (at address@hidden your option) any later version. address@hidden address@hidden Octave is distributed in the hope that it will be useful, but WITHOUT address@hidden ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or address@hidden FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License address@hidden for more details. address@hidden address@hidden You should have received a copy of the GNU General Public License address@hidden along with Octave; see the file COPYING. If not, see address@hidden . + address@hidden Contributing address@hidden Contributing guidelines address@hidden coding standards address@hidden Octave development + +This chapter is dedicated to those who wish to contribute code to Octave. + address@hidden +* How to contribute:: How you may start contributing code. +* General guidelines:: Advices applicable to any type of source. +* Octave sources (m-files):: Guidelines for m-file coding. +* C++ sources:: Guidelines for C++ coding. +* Other sources:: Guidelines for other languages. address@hidden menu + address@hidden How to contribute address@hidden How to contribute +The mailing list for Octave development discussion and sending contributions is address@hidden@@octave.org}. This concerns the development of Octave +core, i.e. code that goes to Octave directly. You may consider developing +and publishing a package instead; a great place for this is the allied Octave-Forge +project (see @url{http://octave.sf.net}). Note that the Octave project is +inherently more conservative and follows narrower rules. + +The preferable form of contribution is creating a Mercurial changeset and +sending it via e-mail to the octave-maintainers mailing list. Mercurial is the +SCM system currently used to develop Octave (it replaced the older CVS). Other +forms of contributions (e.g. simple diff patches) are also acceptable, but they +slow down the review process. If you want to make more contributions, you +should really get familiar with Mercurial. A good place to start is address@hidden://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}. +A simplified contribution sequence could look like this: address@hidden +hg clone http://www.octave.org/hg/octave +cd octave +# change some sources... +hg commit -m "make Octave the coolest software ever" +hg export ../cool.diff +# send ../cool.diff via email address@hidden example + address@hidden General guidelines address@hidden General guidelines + +All Octave's sources are distributed under the General Public License (GPL). +Currently, Octave uses GPL version 3. +For details about this license, see @url{http://www.gnu.org/licenses/gpl.html}. +Therefore, whenever you create a new source file, it should have a comment +header like this: address@hidden +## Copyright (C) 1996, 1997, 2007 John W. Eaton +## +## This file is part of Octave. +## +## Octave is free software; you can redistribute it and/or +## modify it under the terms of the GNU General Public +## License as published by the Free Software Foundation; +## either version 3 of the License, or (at your option) any +## later version. +## +## Octave is distributed in the hope that it will be useful, +## but WITHOUT ANY WARRANTY; without even the implied +## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +## PURPOSE. See the GNU General Public License for more +## details. +## +## You should have received a copy of the GNU General Public +## License along with Octave; see the file COPYING. If not, +## see . address@hidden example + +Always include ChangeLog entries in changesets. After making making your +source changes, record and briefly describe the changes in the nearest +ChangeLog file upwards in the directory tree. Use the previous entries +as a template. Your entry should contain your name and email, and +the path to the modified source file relative to the parent directory of +the ChangeLog file. If there are more functions in the file, +you should also include the name of the modified function (in parentheses +after file path). Example: address@hidden +2008-04-02 David Bateman + + * graphics.cc (void gnuplot_backend::close_figure (const + octave_value&) const): Allow for an input and output stream. address@hidden example + +The ChangeLog entries should describe what is changed, not why. +The reason of the change should appear in the commit message. + address@hidden Octave sources (m-files) address@hidden Octave sources (m-files) + +Don't use tabs. Tabs cause trouble. If you are used to them, set up your editor +so that it converts tabs to spaces. Indent the bodies of the statement blocks. +Recommended indent is 2 spaces. When calling functions, put spaces after +commas and before the calling parentheses, like this: address@hidden + x = max (sin (y+3), 2); address@hidden example +In indexing expression, do not put a space after the identifier (this +differentiates indexing and function calls nicely). The space after comma +is not necessary if index expressions are simple, i.e. you may write address@hidden + A(:,i,j) address@hidden example +but address@hidden + A([1:i-1;i+1:n], XI(:,2:n-1)) address@hidden example + +Use lowercase names if possible. Uppercase is acceptable for variable +names consisting of 1-2 letters. Do not use mixed case names. Function +names must be lowercase. Function names are global, so choose them wisely. + +Always use a specific end-of-block statement (like @code{endif}, @code{endswitch}) +rather than generic @code{end}. Enclose the @code{if}, @code{while}, address@hidden and @code{switch} conditions in parentheses, like in C: address@hidden +if (isvector (a)) + s = sum(a); +endif address@hidden example +Do not do this, however, with @code{for}: address@hidden +for i = 1:n + b(i) = sum (a(:,i)); +endfor address@hidden example + address@hidden C++ sources address@hidden C++ sources + +Don't use tabs. Tabs cause trouble. If you are used to them, set up your editor +so that it converts tabs to spaces. +Format function headers like this: address@hidden +static bool +matches_patterns (const string_vector& patterns, int pat_idx, + int num_pat, const std::string& name) address@hidden example +so that the function name starts in column 1, ant multi-line argument lists are +aligned on the first char after the open parenthesis. +You should put a space after the left open parenthesis and after commas, for both +function definitions and function calls. + +Recommended indent is 2 spaces. When indenting, indent the statement after +control structures (like @code{if}, @code{while} etc.). If there is a +compound statement, indent @i{both} the curly braces and the body of the +statement (so that the body gets indented by @i{two} indents). Example: address@hidden +if (have_args) + @{ + idx.push_back (first_args); + have_args = false; + @} +else + idx.push_back (make_value_list (*p_args, *p_arg_nm, &tmp)); address@hidden example +If you have nested @code{if} statements, use extra braces for extra clarification. + +Split long expressions in such a way that a continuation line starts with an operator +rather than identifier. If the split occurs inside braces, continuation should +be aligned with the first char after the innermost braces enclosing the split. +Example: address@hidden +SVD::type type = ((nargout == 0 || nargout == 1) + ? SVD::sigma_only + : (nargin == 2) ? SVD::economy : SVD::std); address@hidden example +Consider putting extra braces around a multiline expression to make it more +readable, even if they are not necessary. Also, do not hesitate to put extra +braces anywhere if it improves clarity. + +Try declaring variables just before they're needed. Use local variables of blocks - it +helps optimization. Don't write multi-line variable declaration with a single type +specification and multiple variables. If the variables don't fit on single line, +repeat the type specification. Example: address@hidden +octave_value retval; + +octave_idx_type nr = b.rows (); +octave_idx_type nc = b.cols (); + +double d1, d2; address@hidden example + +Use lowercase names if possible. Uppercase is acceptable for variable +names consisting of 1-2 letters. Do not use mixed case names. + +Try to use Octave's types and classes if possible. Otherwise, try to use +C++ standard library. Use of STL containers and algorithms is encouraged. +Use templates wisely to reduce code duplication. Avoid comma expressions, +labels and gotos, and explicit typecasts. If you need +to typecast, use the modern C++ casting operators. In functions, +try to reduce the number of @code{return} statements - use nested @code{if} +statements if possible. + address@hidden Other sources address@hidden Other sources diff --git a/doc/interpreter/octave.texi b/doc/interpreter/octave.texi --- a/doc/interpreter/octave.texi +++ b/doc/interpreter/octave.texi @@ -184,9 +184,11 @@ * Packages:: * Dynamically Linked Functions:: * Test and Demo Functions:: +* * Tips:: * Trouble:: If you have trouble installing Octave. * Installation:: How to configure, compile and install Octave. +* Contributing:: How to contribute to Octave. * Emacs:: @c * Grammar:: * Copying:: The GNU General Public License. @@ -647,6 +649,7 @@ @include tips.texi @include bugs.texi @include install.texi address@hidden contrib.texi @include emacs.texi @c @include grammar.texi @include gpl.texi