Editing Commit message guidelines

Jump to navigation Jump to search

Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Latest revision Your text
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.
 +
Here there is an example:
 +
<pre>
 +
Give message id to undefined function error
 +
 +
* pt-id.cc (tree_identifier::eval_undefined_error): used
 +
  ::error_with_id instead of ::error to report undefined functions
 +
  with id.
 +
</pre>
  
 
=== One-line description ===  
 
=== One-line description ===  
  
The commit message should have a brief a one-line description of what the
+
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).
commit does. Keep it short, preferably under 80 characters. If you are
 
patching a bug, this one-line explanation should mention the bug number
 
at the end like so: {{codeline|... (bug #12345)}}. Omit final period (full stop).
 
  
If your change only touches one file, then the filename of that file should
+
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:
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.
 
 
 
In addition, there are two prefixes for special commits:
 
  
 
* 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 is small and only touches one file then this is
+
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.
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
+
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.
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>
 
  
Note the newline for describing the change to a different function. General
+
Individual files you touched get their changes separately enumerated. If there a particular C or C++ function you changed, the general format is
GNU style guidelines can be followed here, so that similar changes to
 
different files can be grouped.
 
  
For m-script and Fortran sources, the function name can be omitted if
+
    * file.cc (class1::function1): Make change foo.
the m-script only contains one file. For changes outside of functions
+
      (class2::function2): Make change bar.
or classes, of course the parenthetical (function) or (class::function)
 
specifiers can also be omitted.
 
  
=== Wording ===
+
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.
  
Please write "New function" instead of "Added function" or "Return retval"
+
For style points, please also write "New function" instead of "Added function" or "Return retval" instead of "Changed to return retval".
instead of "Changed to return retval".
 
  
Never write "Fixed bug" or similar. That doesn't add any specific
+
And please, never "Fixed bug" or similar. That doesn't add any specific information about what was changed.
information about what was changed.
 
  
The commit message should describe what was changed, not why it 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.
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 ==
  
<pre>
+
* standard commit messages
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 99: Line 68:
 
  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 107: Line 75:
 
* 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 116: Line 83:
 
</pre>
 
</pre>
  
=== One line commit examples ===
+
* For short and very simple commit messages under 80 characters.  
 
+
<pre>@ftp/cd.m: Fix docstring.</pre>
This examples are the rare cases where only one file is modified and the
+
<pre>strjoin.m: delimiter can include escape sequences (matlab compatibility)</pre>
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]]

Please note that all contributions to Octave may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see Octave:Copyrights for details). Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel Editing help (opens in new window)

Template used on this page: