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 7: Line 7:
 
For more options, see [https://www.mercurial-scm.org/repo/hg/help/log the Mercurial manual].
 
For more options, see [https://www.mercurial-scm.org/repo/hg/help/log the Mercurial manual].
  
== Examples ==
 
  
<pre>
+
== Guidelines ==
look for methods before constructors
+
 
 +
General structure of a commit message:
 +
 
 +
:: '''One-line description'''
 +
:: ''Empty line''
 +
:: '''Body of the commit message'''
 +
 
 +
=== One-line description ===
 +
 
 +
The commit message should start with a brief one-line description of what the
 +
commit does. Keep it short, no longer than 80 characters. If you are working
 +
on a bug or applying a patch, this one-line explanation should mention the bug
 +
or patch number at the end like so: {{codeline|... (bug #12345)}}. Do not end
 +
the first line with a period (full stop).
 +
 
 +
If your change only touches one file, then the name of that file can 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 a few prefixes for certain types of commits:
 +
 
 +
* 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.
 +
* build: for changes to the build system, for example autoconf or automake files.
 +
 
 +
If your change is small and only touches one file, then the one-line
 +
description may serve as the entire commit message.
  
* symtab.cc (symbol_table::fcn_info::fcn_info_rep::find):
+
=== Body of the commit message ===
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>
+
If there is more than one file touched in different ways and the one-line
allow abbreviations for optimset and optimget (bug #38999)
+
description isn't enough to describe all changes, the commit message needs a
 +
full-body description.
  
* optimset.m, optimget.m: Handle abbreviated keys and warn for
+
Each individual file changed by a commmit must have its changes enumerated.
ambiguous abbreviations. New tests.
+
For changes affecting specific C++ functions, each function name is listed in
</pre>
+
parentheses. For example
  
 
<pre>
 
<pre>
add format option to ticklabel (bug #34906)
+
* file.cc (class1::function1): Add something.
 +
(function2, function3): Delete something else.
 +
</pre>
  
* graphics.cc: add new functions to support different input arguments to
+
For changes affecting specific Octave built-ins, each built-in name is listed
  xyzticklabel. Add tests.
+
in parentheses with an "F" prefix, an implementation detail. For example
* graphics.in.h: define set_xyzticklabel as external function
 
</pre>
 
  
 
<pre>
 
<pre>
tag symbols in indexed assignments as variables (bug #39240)
+
* data.cc (Fcolumns): Return columns.
 +
</pre>
  
* pt-arg-list.cc (tree_argument_list::variable_names): Also return the
+
When the same change is applied to a series of files, or to a set of functions
  symbol names from index expressions.
+
in a single file, the file or function names may be grouped to shorten the
* parser.tst: New test.
+
commit message. For example:
</pre>
 
  
 
<pre>
 
<pre>
tar, untar, unpack: Add support for BSD tar (bug #53695)
+
* file1.cc, file2.cc, file3.cc, file4.cc: Include <sys/types.h>.
 
+
* memory.cc (function1, function2, function3): Throw error if empty.
* tar_is_bsd.m: New function.
 
* tar.m: Use it to determine how to run tar and parse command output.
 
* unpack.m: Likewise.
 
 
</pre>
 
</pre>
  
=== One line examples ===
+
Each line of the commit message body should also be kept under 80 columns. The
 +
GNU standards recommend starting a new line for each parenthesized function,
 +
but if the line is short enough, we often avoid an extra newline. For example
  
This examples are the rare cases where only one file is modified and the change is simple enough:
+
<pre>
 +
* file.cc (function1): Add an option.  (function2): Add another option.
 +
</pre>
  
maint: merge stable to default.
+
Only the last file name component is typically needed, since most files have
+
unique names across the entire repository. One notable exception are the
maint: merge away accidental head.
+
{{codeline|module.mk}} files in every directory, they should include the
+
complete directory and file name. For example
maint: Strip trailing whitespace from source files.
 
 
maint: Update gnulib to latest changes.
 
 
doc: grammarcheck documentation for 4.2 release.
 
 
pkg.m4: update to lastest version as released with pkg-config 0.29 (bug #48775)
 
 
uigetfile.m: allow path names as input arg (bug #48828)
 
  
== Guidelines ==
+
<pre>
 +
* doc/interpreter/module.mk (dist_man_MANS): Include foo.1 in the list.
 +
</pre>
  
The general structure of a commit message should be clear from the examples:
+
Avoid abbreviating or using shell globs or patterns when listing the names of
 +
files affected by a change, even when they have the same name with different
 +
file extensions. For example
  
* After the first line, leave one blank line.
+
<pre>
* Do not end the first line with a period (full stop).
+
* oct-fftw.cc, oct-fftw.h (octave_fftw_version): New function.
* Keep it short, no longer than 80 characters.
+
</pre>
* Add the bug number, e.g. <code>(bug #12345)</code>, where applicable.
 
* Use prefixes where applicable:
 
** <code>build:</code> for changes to the build system, for example autoconf or automake files.
 
** <code>doc:</code> for changes to the documentation.
 
** <code>gui:</code> for changes to the graphical user interface.
 
** <code>maint:</code> for reorganization of the sources that do not change the source. Regular merge commits are a prominent example.
 
** <code>test:</code> for changes to [[Tests]] only, e.g. new/removed BISTs, changed tolerances, etc.
 
  
 +
For m-file and Fortran sources, the function name can be omitted if the file
 +
contains only one function. For changes outside of functions or classes, of
 +
course the parenthetical (function) or (class::function) specifiers can also
 +
be omitted.
  
 
=== Wording ===
 
=== Wording ===
Line 104: Line 117:
 
The commit message should describe '''what''' was changed, not '''why''' it was changed. Any explanations should appear as comments in the code, particularly if there is something that might not be obvious to someone reading it later.
 
The commit message should describe '''what''' was changed, not '''why''' it was changed. Any explanations should appear as comments in the code, particularly if there is something that might not be obvious to someone reading it later.
  
=== Body of the commit message ===
+
== Examples ==
  
Each individual file changed by a commit must have its changes enumerated. For changes affecting specific C++ functions, each function name is listed in parentheses. For example
+
<pre>
 +
look for methods before constructors
  
* file.cc (class1::function1): Add something.
+
* symtab.cc (symbol_table::fcn_info::fcn_info_rep::find):
(function2, function3): Delete something else.
+
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>
  
For changes affecting specific Octave built-ins, each built-in name is listed in parentheses with an "F" prefix, an implementation detail. For example
+
<pre>
 +
allow abbreviations for optimset and optimget (bug #38999)
  
* data.cc (Fcolumns): Return columns.
+
* optimset.m, optimget.m: Handle abbreviated keys and warn for
 +
ambiguous abbreviations. New tests.
 +
</pre>
  
When the same change is applied to a series of files, or to a set of functions in a single file, the file or function names may be grouped to shorten the commit message. For example:
+
<pre>
 +
add format option to ticklabel (bug #34906)
  
* file1.cc, file2.cc, file3.cc, file4.cc: Include <sys/types.h>.
+
* graphics.cc: add new functions to support different input arguments to
* memory.cc (function1, function2, function3): Throw error if empty.
+
  xyzticklabel. Add tests.
 +
* graphics.in.h: define set_xyzticklabel as external function
 +
</pre>
  
Each line of the commit message body should also be kept under 80 columns. The GNU standards recommend starting a new line for each parenthesized function, but if the line is short enough, we often avoid an extra newline. For example
+
<pre>
 +
tag symbols in indexed assignments as variables (bug #39240)
  
* file.cc (function1): Add an option.  (function2): Add another option.
+
* pt-arg-list.cc (tree_argument_list::variable_names): Also return the
 +
  symbol names from index expressions.
 +
* parser.tst: New test.
 +
</pre>
 +
 
 +
<pre>
 +
tar, untar, unpack: Add support for BSD tar (bug #53695)
  
Only the last file name component is typically needed, since most files have unique names across the entire repository. One notable exception are the {{codeline|module.mk}} files in every directory, they should include the complete directory and file name. For example
+
* tar_is_bsd.m: New function.
 +
* tar.m: Use it to determine how to run tar and parse command output.
 +
* unpack.m: Likewise.
 +
</pre>
  
* doc/interpreter/module.mk (dist_man_MANS): Include foo.1 in the list.
+
=== One line commit examples ===
  
Avoid abbreviating or using shell globs or patterns when listing the names of files affected by a change, even when they have the same name with different file extensions. For example
+
This examples are the rare cases where only one file is modified and the
 +
change is simple enough:
  
* oct-fftw.cc, oct-fftw.h (octave_fftw_version): New function.
+
<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>
  
For m-file and Fortran sources, the function name can be omitted if the file contains only one function. For changes outside of functions or classes, of course the parenthetical (function) or (class::function) specifiers can also be omitted.
 
  
 
[[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: