# 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