# HG changeset patch # User Jordi Gutiérrez Hermoso # Date 1316480503 18000 # Node ID d624b6f216ac62e25cf25786bda3dbe814342dcf # Parent 9efb676b34ac0e45bc9d48c75d9312f74fb4681e Update guidelines on how to write commit messages and changelogs diff -r 9efb676b34ac -r d624b6f216ac doc/interpreter/contrib.txi --- a/doc/interpreter/contrib.txi Mon Sep 19 20:18:47 2011 -0400 +++ b/doc/interpreter/contrib.txi Mon Sep 19 20:01:43 2011 -0500 @@ -6,12 +6,12 @@ @c under the terms of the GNU General Public License as published by the @c Free Software Foundation; either version 3 of the License, or (at @c your option) any later version. -@c +@c @c Octave is distributed in the hope that it will be useful, but WITHOUT @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License @c for more details. -@c +@c @c You should have received a copy of the GNU General Public License @c along with Octave; see the file COPYING. If not, see @c . @@ -23,7 +23,7 @@ This chapter is dedicated to those who wish to contribute code to Octave. -@menu +@menu * How to Contribute:: * General Guidelines:: * Octave Sources (m-files):: @@ -56,7 +56,7 @@ @example @group hg clone http://www.octave.org/hg/octave - # make a local copy of the octave + # make a local copy of the octave # source repository cd octave # change some sources@dots{} @@ -71,13 +71,13 @@ @end example You may want to get familiar with Mercurial queues to manage your -changesets. Here is a slightly more complex example using Mercurial +changesets. Here is a slightly more complex example using Mercurial queues, where work on two unrelated changesets is done in parallel and -one of the changesets is updated after discussion on the maintainers mailing -list: +one of the changesets is updated after discussion on the maintainers +mailing list: @example -hg qnew nasty_bug # create a new patch +hg qnew nasty_bug # create a new patch # change sources@dots{} hg qref # save the changes into the patch # change even more@dots{} @@ -89,7 +89,7 @@ hg qpop # undo the application of the patch # and remove the changes from the # source tree -hg qnew doc_improvements # create an unrelated patch +hg qnew doc_improvements # create an unrelated patch # change doc sources@dots{} hg qref -m "could not find myfav.m in the doc" # save the changes into the patch @@ -122,7 +122,7 @@ ## 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 +## either version 3 of the License, or (at your option) any ## later version. ## ## Octave is distributed in the hope that it will be useful, @@ -136,40 +136,54 @@ ## see . @end example -Always include ChangeLog entries in changesets. After 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: +Always include commit messages in changesets. After making your source +changes, record and briefly describe the changes in your commit message. +You should have previously configured your @file{.hgrc} (or +@file{Mercurial.ini} on Windows) with your name and email, which will +get automatically added to your commit message. Your commit message +should have a brief one-line explanation of what the commit does. If you +are patching a bug, this one-line explanation should mention the bug +number at the end. If your change is small and only touches one file, +this is typically sufficient. If you are modifying several files or +several parts of one file, you should enumerate your changes roughly +following the GNU coding standards on changelogs, like the following +example: @example @group -2010-04-13 David Bateman + look for methods before constructors + + * symtab.cc (symbol_table::fcn_info::fcn_info_rep::find): + Look for class methods before constructors, contrary to Matlab + documentation. - * DLD-FUNCTIONS/regexp.cc (octregexp_list): Handle repeated matches - in the list of matches returned by pcre. + * test/ctor-vs-method: New directory of test classes. + * test/test_ctor_vs_method.m: New file. + * test/Makefile.am: Include ctor-vs-method/module.mk. + (FCN_FILES): Include test_ctor_vs_method.m in the list. + + * DLD-FUNCTIONS/regexp.cc (octregexp_list): Handle repeated matches + in the list of matches returned by pcre. @end group @end example @noindent -The ChangeLog entries should describe what is changed, not why. Any -explanation of why a change is needed should appear as comments in the -code, particularly if there is something that might not be obvious to -someone reading it later. +In this example, the names of files is mentioned, and in parentheses the +name of the function in that file that was modified. There is no need to +mention the function for m-files that only contain one function. The +commit message should describe what is changed, not why. Any explanation +of why a change is needed should appear as comments in the code, +particularly if there is something that might not be obvious to someone +reading it later. -When submitting code which addresses a known bug on the Octave bug tracker -(@url{http://bugs.octave.org}), please add '(bug #XXXXX)' to the ChangeLog -and Mercurial commit messages. Example: +When submitting code which addresses a known bug on the Octave bug +tracker (@url{http://bugs.octave.org}), please add '(bug #XXXXX)' to the +commit messages. Example: @example @group -2011-03-29 Michael Creel - - * statistics/base/ols.m: Fix erroneous degrees of freedom when - computing the covariance estimator (bug #32892). + * ols.m: Fix erroneous degrees of freedom when computing the + covariance estimator (bug #32892). @end group @end example @@ -208,7 +222,7 @@ @end example @noindent -but +but @example A([1:i-1;i+1:n], XI(:,2:n-1)) @@ -223,7 +237,7 @@ @code{endswitch}) rather than generic @code{end}. Enclose the @code{if}, @code{while}, @code{until} and @code{switch} -conditions in parentheses, like in C: +conditions in parentheses, like in C: @example @group @@ -286,7 +300,7 @@ @noindent If you have nested @code{if} statements, use extra braces for extra -clarification. +clarification. Split long expressions in such a way that a continuation line starts with an operator rather than identifier. If the split occurs inside