Commit message guidelines: Difference between revisions

(Shorten intro.)
(→‎Examples: Update punctuation to GNU style)
 
(6 intermediate revisions by 2 users not shown)
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 ==


== Guidelines ==
<pre>
Look for methods before constructors.


General structure of a commit message:
* 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>


:: '''One-line description'''
<pre>
:: ''Empty line''
Allow abbreviations for optimset and optimget (bug #38999).
:: '''Body of the commit message'''


=== One-line description ===
* optimset.m, optimget.m: Handle abbreviated keys and warn for
ambiguous abbreviations. New tests.
</pre>


The commit message should start with a brief one-line description of what the
<pre>
commit does. Keep it short, no longer than 80 characters. If you are working
Add format option to ticklabel (bug #34906).
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
* graphics.cc: Add new functions to support different input arguments to
prefix of the one-line description. If it's a C++ or C file, the function or
  xyzticklabel. Add tests.
class that is being modified should be included in the parenthetical remark,
* graphics.in.h: Define set_xyzticklabel as external function.
as in the full body of the commit message.
</pre>


In addition, there are a few prefixes for certain types of commits:
<pre>
Tag symbols in indexed assignments as variables (bug #39240).


* maint: for reorganisation of the sources that do not change the source. Regular merge commits are a prominent example.
* pt-arg-list.cc (tree_argument_list::variable_names): Also return the
* doc: for changes to the documentation.
  symbol names from index expressions.
* build: for changes to the build system, for example autoconf or automake files.
* parser.tst: New test.
 
If your change is small and only touches one file, then the one-line
description may serve as the entire 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.
 
Each individual file changed by a commmit must have its changes enumerated.
For changes affecting specific C++ functions, each function name is listed in
parentheses. For example
 
<pre>
* file.cc (class1::function1): Add something.
(function2, function3): Delete something else.
</pre>
</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>
<pre>
* data.cc (Fcolumns): Return columns.
tar, untar, unpack: Add support for BSD tar (bug #53695).
</pre>


When the same change is applied to a series of files, or to a set of functions
* tar_is_bsd.m: New function.
in a single file, the file or function names may be grouped to shorten the
* tar.m: Use it to determine how to run tar and parse command output.
commit message. For example:
* unpack.m: Likewise.
 
<pre>
* file1.cc, file2.cc, file3.cc, file4.cc: Include <sys/types.h>.
* memory.cc (function1, function2, function3): Throw error if empty.
</pre>
</pre>


Each line of the commit message body should also be kept under 80 columns. The
=== One line examples ===
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>
This examples are the rare cases where only one file is modified and the change is simple enough:
* file.cc (function1): Add an option.  (function2): Add another option.
</pre>


Only the last file name component is typically needed, since most files have
maint: Merge stable to default.
unique names across the entire repository. One notable exception are the
{{codeline|module.mk}} files in every directory, they should include the
maint: Merge away accidental head.
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 latest version as released with pkg-config 0.29 (bug #48775).
uigetfile.m: Allow path names as input arg (bug #48828).


<pre>
== Guidelines ==
* doc/interpreter/module.mk (dist_man_MANS): Include foo.1 in the list.
</pre>


Avoid abbreviating or using shell globs or patterns when listing the names of
The general structure of a commit message should be clear from the examples:
files affected by a change, even when they have the same name with different
file extensions. For example


<pre>
* After the first line, leave one blank line.
* oct-fftw.cc, oct-fftw.h (octave_fftw_version): New function.
* Do not end the first line with a period (full stop).
</pre>
* Keep it short, no longer than 80 characters.
* 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 117: Line 104:
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.


== Examples ==
=== Body of the commit message ===
 
<pre>
look for methods before constructors


* symtab.cc (symbol_table::fcn_info::fcn_info_rep::find):
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
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>
* file.cc (class1::function1): Add something.
allow abbreviations for optimset and optimget (bug #38999)
(function2, function3): Delete something else.


* optimset.m, optimget.m: Handle abbreviated keys and warn for
For changes affecting specific Octave built-ins, each built-in name is listed in parentheses with an "F" prefix, an implementation detail. For example
ambiguous abbreviations. New tests.
</pre>


<pre>
* data.cc (Fcolumns): Return columns.
add format option to ticklabel (bug #34906)


* graphics.cc: add new functions to support different input arguments to
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:
  xyzticklabel. Add tests.
* graphics.in.h: define set_xyzticklabel as external function
</pre>


<pre>
* file1.cc, file2.cc, file3.cc, file4.cc: Include <sys/types.h>.
tag symbols in indexed assignments as variables (bug #39240)
* memory.cc (function1, function2, function3): Throw error if empty.


* pt-arg-list.cc (tree_argument_list::variable_names): Also return the
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
  symbol names from index expressions.
* parser.tst: New test.
</pre>


<pre>
* file.cc (function1): Add an option.  (function2): Add another option.
tar, untar, unpack: Add support for BSD tar (bug #53695)


* tar_is_bsd.m: New function.
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.m: Use it to determine how to run tar and parse command output.
* unpack.m: Likewise.
</pre>


=== One line commit examples ===
* doc/interpreter/module.mk (dist_man_MANS): Include foo.1 in the list.


This examples are the rare cases where only one file is modified and the
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
change is simple enough:


<pre>maint: merge away accidental head.</pre>
* oct-fftw.cc, oct-fftw.h (octave_fftw_version): New function.
<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]]

Latest revision as of 12:10, 14 March 2023

Commit messages for Mercurial get automatically distilled into GNU Changelog entries. The GNU coding standards have some guidelines for how to write Changelogs, and since Octave is a GNU project, we try to produce Changelogs in this style.

You can see how Mercurial will produce the Changelog-style output with the following command:

 hg log --template changelog

For more options, see the Mercurial manual.

ExamplesEdit

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.
Allow abbreviations for optimset and optimget (bug #38999).

* optimset.m, optimget.m: Handle abbreviated keys and warn for
 ambiguous abbreviations. New tests.
Add format option to ticklabel (bug #34906).

* graphics.cc: Add new functions to support different input arguments to
  xyzticklabel. Add tests.
* graphics.in.h: Define set_xyzticklabel as external function.
Tag symbols in indexed assignments as variables (bug #39240).

* pt-arg-list.cc (tree_argument_list::variable_names): Also return the
  symbol names from index expressions.
* parser.tst: New test.
tar, untar, unpack: Add support for BSD tar (bug #53695).

* tar_is_bsd.m: New function.
* tar.m: Use it to determine how to run tar and parse command output.
* unpack.m: Likewise.

One line examplesEdit

This examples are the rare cases where only one file is modified and the change is simple enough:

maint: Merge stable to default.

maint: Merge away accidental head.

maint: Strip trailing whitespace from source files.

maint: Update gnulib to latest changes.

doc: Grammarcheck documentation for 4.2 release.

pkg.m4: Update to latest version as released with pkg-config 0.29 (bug #48775).

uigetfile.m: Allow path names as input arg (bug #48828).

GuidelinesEdit

The general structure of a commit message should be clear from the examples:

  • After the first line, leave one blank line.
  • Do not end the first line with a period (full stop).
  • Keep it short, no longer than 80 characters.
  • Add the bug number, e.g. (bug #12345), where applicable.
  • Use prefixes where applicable:
    • build: for changes to the build system, for example autoconf or automake files.
    • doc: for changes to the documentation.
    • gui: for changes to the graphical user interface.
    • maint: for reorganization of the sources that do not change the source. Regular merge commits are a prominent example.
    • test: for changes to Tests only, e.g. new/removed BISTs, changed tolerances, etc.


WordingEdit

bad good
"Added function" "New function"
"Changed to return retval" "Return retval"
"Fixed bug" Write what has changed.

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 messageEdit

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

* file.cc (class1::function1): Add something.
(function2, function3): Delete something else.

For changes affecting specific Octave built-ins, each built-in name is listed in parentheses with an "F" prefix, an implementation detail. For example

* data.cc (Fcolumns): Return columns.

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:

* file1.cc, file2.cc, file3.cc, file4.cc: Include <sys/types.h>.
* memory.cc (function1, function2, function3): Throw error if empty.

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

* file.cc (function1): Add an option.  (function2): Add another option.

Only the last file name component is typically needed, since most files have unique names across the entire repository. One notable exception are the module.mk files in every directory, they should include the complete directory and file name. For example

* doc/interpreter/module.mk (dist_man_MANS): Include foo.1 in the list.

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

* oct-fftw.cc, oct-fftw.h (octave_fftw_version): New function.

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.