Changes

Jump to navigation Jump to search
473 bytes added ,  13:51, 24 August 2016
add more examples and explanation from the manual
Line 12: Line 12:     
   hg log --style changelog >> octave_changelogs.log
 
   hg log --style changelog >> octave_changelogs.log
 +
    
== Guidelines ==
 
== Guidelines ==
 +
 
General structure of a commit message:
 
General structure of a commit message:
 +
 
:: '''One-line description'''
 
:: '''One-line description'''
:: Empty line
+
:: ''Empty line''
 
:: '''Body of the commit message'''
 
:: '''Body of the commit message'''
   −
Each part is explained in detail below.
+
=== One-line description ===
Here there is an example:
  −
<pre>
  −
Give message id to undefined function error
     −
* pt-id.cc (tree_identifier::eval_undefined_error): used
+
The commit message should have a brief a one-line description of what the
  ::error_with_id instead of ::error to report undefined functions
+
commit does. Keep it short, preferably under 80 characters. If you are
  with id.
+
patching a bug, this one-line explanation should mention the bug number
</pre>
+
at the end like so: {{codeline|... (bug #12345)}}. Omit final period (full stop).
   −
=== One-line description ===
+
If your change only touches one file, then the filename of that file should
 +
be the prefix of the one-line description. If it's a C++ or C file, the
 +
function or class that is being modified should be included in the
 +
parenthetical remark, as in the full body of the commit message.
   −
The commit message has a one-line description. Keep it short, preferrably under 80 characters. If you're squashing a bug, the bug number you're squashing should be included in this one-line description, like so at the end: <tt>(bug #12345)</tt>. Omit final period (full stop).
+
In addition, there are two prefixes for special commits:
 
  −
Sometimes the one-line description is sufficient, for small changes. In that case, we use the following prefixes to give a description of what the small change is:
      
* maint: for reorganisation of the sources that do not change the source. Regular merge commits are a prominent example.
 
* maint: for reorganisation of the sources that do not change the source. Regular merge commits are a prominent example.
 
* doc: for changes to the documentation.
 
* doc: for changes to the documentation.
   −
If your change only touches one file, then the filename of that file should be the prefix of the one-line description. If it's a C++ or C file, the function or class that is being modified should be included in the parenthetical remark, as in the full body of the commit message.
+
If your change is small and only touches one file then this is
 +
typically sufficient.
    
=== Body of the commit message ===
 
=== Body of the commit message ===
   −
If there is more than one file touched in different ways and the one-line description isn't enough to describe all changes, the commit message needs a full-body description.
+
If there is more than one file touched in different ways and the one-line
 +
description isn't enough to describe all changes, the commit message needs
 +
a full-body description.
 +
 
 +
Individual files you touched get their changes separately enumerated. If
 +
there a particular C or C++ function you changed, the general format is
 +
 
 +
<pre>
 +
* file.cc (class1::function1): Make change foo.
 +
(class2::function2): Make change bar.
 +
</pre>
   −
Individual files you touched get their changes separately enumerated. If there a particular C or C++ function you changed, the general format is
+
Note the newline for describing the change to a different function. General
 +
GNU style guidelines can be followed here, so that similar changes to
 +
different files can be grouped.
   −
    * file.cc (class1::function1): Make change foo.
+
For m-script and Fortran sources, the function name can be omitted if
      (class2::function2): Make change bar.
+
the m-script only contains one file. For changes outside of functions
 +
or classes, of course the parenthetical (function) or (class::function)
 +
specifiers can also be omitted.
   −
Note the newline for describing the change to a different function. General GNU style guidelines can be followed here, so that similar changes to different files can be grouped.
+
=== Wording ===
   −
For style points, please also write "New function" instead of "Added function" or "Return retval" instead of "Changed to return retval".
+
Please write "New function" instead of "Added function" or "Return retval"
 +
instead of "Changed to return retval".
   −
And please, never "Fixed bug" or similar. That doesn't add any specific information about what was changed.
+
Never write "Fixed bug" or similar. That doesn't add any specific
 +
information about what was changed.
   −
The changelog info in the commit message should say what changed, not why. If you need to explain why, that info should probably go in comments in the code.
+
The commit message should describe what was changed, not why it was changed.
 +
Any explanation for 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.
   −
For m-script and Fortran sources, the function name can be omitted if the m-script only contains one file. For changes outside of functions or classes, of course the parenthetical (function) or (class::function) specifiers can also be omitted.
      
== Examples ==
 
== Examples ==
   −
* standard commit messages
+
<pre>
 +
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.
 +
* 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.
 +
</pre>
 +
 
 
<pre>
 
<pre>
 
allow abbreviations for optimset and optimget (bug #38999)
 
allow abbreviations for optimset and optimget (bug #38999)
Line 68: Line 99:  
  ambiguous abbreviations. New tests.
 
  ambiguous abbreviations. New tests.
 
</pre>
 
</pre>
 +
 
<pre>
 
<pre>
 
add format option to ticklabel (bug #34906)
 
add format option to ticklabel (bug #34906)
Line 75: Line 107:  
* graphics.in.h: define set_xyzticklabel as external function
 
* graphics.in.h: define set_xyzticklabel as external function
 
</pre>
 
</pre>
 +
 
<pre>
 
<pre>
 
tag symbols in indexed assignments as variables (bug #39240)
 
tag symbols in indexed assignments as variables (bug #39240)
Line 83: Line 116:  
</pre>
 
</pre>
   −
* For short and very simple commit messages under 80 characters.  
+
=== One line commit examples ===
<pre>@ftp/cd.m: Fix docstring.</pre>
+
 
<pre>strjoin.m: delimiter can include escape sequences (matlab compatibility)</pre>
+
This examples are the rare cases where only one file is modified and the
 +
change is simple enough:
 +
 
 +
<pre>maint: merge away accidental head.</pre>
 +
<pre>maint: Strip trailing whitespace from source files.</pre>
 +
<pre>maint: Update gnulib to latest changes.</pre>
 +
<pre>maint: Periodic merge of stable to default.</pre>
 +
<pre>doc: grammarcheck documentation for 4.2 release.</pre>
 +
<pre>pkg.m4: update to lastest version as released with pkg-config 0.29 (bug #48775)</pre>
 +
<pre>uigetfile.m: allow path names as input arg (bug #48828)</pre>
   −
* maintenance or docs commits, no actual code changed
  −
<pre>maint: update config.in.h in .hgignore</pre>
      
[[Category:Development]]
 
[[Category:Development]]

Navigation menu