Commit message guidelines: Difference between revisions

From Octave
Jump to navigation Jump to search
mNo edit summary
(add more examples and explanation from the manual)
(8 intermediate revisions by 5 users not shown)
Line 1: Line 1:
Our commit messages for Mercurial get automatically distilled into GNU Changelog entries. The GNU coding standards have [http://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html some guidelines] for how to write Changelogs, and since Octave is a GNU project, we try to produce Changelogs in this style. However, certain things have to be adapted because the style in there is primarily for C sources, and because we are producing them from Mercurial commit messages.
Our commit messages for Mercurial get automatically distilled into GNU Changelog entries. The GNU coding standards have [http://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html some guidelines] for how to write Changelogs, and since Octave is a GNU project, we try to produce Changelogs in this style. However, certain things have to be adapted because the style in there is primarily for C sources, and because we are producing them from Mercurial commit messages.


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


   hg log --style changelog
   hg log --style changelog
*Note that this command will print all changelogs to the screen, currently including all changelogs back to 2008 and approaching 200,0000 lines of text. You may use the followig command for a paged output:
  hg log --style changelog | less
*Alternatively, you may save the changlogs to a text file. This will permit viewing and searching in a text editor for use in preparing your own commit messages:
  hg log --style changelog >> octave_changelogs.log


== Guidelines ==
== Guidelines ==
General structure of a commit message:
:: '''One-line description'''
:: ''Empty line''
:: '''Body of the commit message'''


=== One-line description ===  
=== One-line description ===  


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).
The commit message should have a brief a one-line description of what the
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).


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:
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.
 
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 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>
 
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.
 
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.
 
=== Wording ===
 
Please write "New function" instead of "Added function" or "Return retval"
instead of "Changed to return retval".
 
Never write "Fixed bug" or similar. That doesn't add any specific
information about what was changed.
 
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.
 
 
== Examples ==
 
<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>
allow abbreviations for optimset and optimget (bug #38999)
 
* optimset.m, optimget.m: Handle abbreviated keys and warn for
ambiguous abbreviations. New tests.
</pre>
 
<pre>
add format option to ticklabel (bug #34906)


Individual files you touched get their changes separately enumerated. If there a particular C or C++ function you changed, the general format is
* graphics.cc: add new functions to support different input arguments to
  xyzticklabel. Add tests.
* graphics.in.h: define set_xyzticklabel as external function
</pre>


    * file.cc (class1::function1): Made change foo.
<pre>
      (class2::function2): Made change bar.
tag symbols in indexed assignments as variables (bug #39240)


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


For style points, please also write "New function" instead of "Added function" or "Return retval" instead of "Changed to return retval".
=== One line commit examples ===


And please, never "Fixed bug" or similar. That doesn't add any specific information about what was changed.
This examples are the rare cases where only one file is modified and the
change is simple enough:


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.
<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-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.


[[Category:Development]]
[[Category:Development]]

Revision as of 17:51, 24 August 2016

Our 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. However, certain things have to be adapted because the style in there is primarily for C sources, and because we are producing them from Mercurial commit messages.

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

 hg log --style changelog
  • Note that this command will print all changelogs to the screen, currently including all changelogs back to 2008 and approaching 200,0000 lines of text. You may use the followig command for a paged output:
 hg log --style changelog | less
  • Alternatively, you may save the changlogs to a text file. This will permit viewing and searching in a text editor for use in preparing your own commit messages:
 hg log --style changelog >> octave_changelogs.log


Guidelines

General structure of a commit message:

One-line description
Empty line
Body of the commit message

One-line description

The commit message should have a brief a one-line description of what the 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: ... (bug #12345). Omit final period (full stop).

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.

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.
  • doc: for changes to the documentation.

If your change is small and only touches one file then this is typically sufficient.

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.

Individual files you touched get their changes separately enumerated. If there a particular C or C++ function you changed, the general format is 

* file.cc (class1::function1): Make change foo. 
(class2::function2): Make change bar.

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.

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.

Wording

Please write "New function" instead of "Added function" or "Return retval" instead of "Changed to return retval".

Never write "Fixed bug" or similar. That doesn't add any specific information about what was changed.

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.


Examples

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.

One line commit examples

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

maint: merge away accidental head.
maint: Strip trailing whitespace from source files.
maint: Update gnulib to latest changes.
maint: Periodic merge of stable to default.
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)
Retrieved from "https://wiki.octave.org/wiki/index.php?title=Commit_message_guidelines&oldid=9533"