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 publish the changes below to finish undoing the edit.

Latest revision Your text
Line 1: Line 1:
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.
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 --template changelog
   hg log --style changelog


For more options, see [https://www.mercurial-scm.org/repo/hg/help/log the Mercurial manual].
== Guidelines ==
 
General structure of a commit message:
== Examples ==
:: '''One-line description'''
:: Empty line
:: '''Body of the commit message'''


Each part is explained in detail below.
Here there is an example:
<pre>
<pre>
Look for methods before constructors.
Give message id to undefined function error


* symtab.cc (symbol_table::fcn_info::fcn_info_rep::find):
* pt-id.cc (tree_identifier::eval_undefined_error): used
Look for class methods before constructors, contrary to Matlab
  ::error_with_id instead of ::error to report undefined functions
documentation.
  with id.
* 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>
=== One-line description ===
Allow abbreviations for optimset and optimget (bug #38999).


* optimset.m, optimget.m: Handle abbreviated keys and warn for
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).
ambiguous abbreviations. New tests.
</pre>


<pre>
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:
Add format option to ticklabel (bug #34906).


* graphics.cc: Add new functions to support different input arguments to
* maint: for reorganisation of the sources that do not change the source. Regular merge commits are a prominent example.
  xyzticklabel. Add tests.
* doc: for changes to the documentation.
* graphics.in.h: Define set_xyzticklabel as external function.
</pre>


<pre>
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.
Tag symbols in indexed assignments as variables (bug #39240).


* pt-arg-list.cc (tree_argument_list::variable_names): Also return the
=== Body of the commit message ===
  symbol names from index expressions.
* parser.tst: New test.
</pre>


<pre>
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.
tar, untar, unpack: Add support for BSD tar (bug #53695).


* tar_is_bsd.m: New function.
Individual files you touched get their changes separately enumerated. If there a particular C or C++ function you changed, the general format is
* tar.m: Use it to determine how to run tar and parse command output.
* unpack.m: Likewise.
</pre>


=== One line examples ===
    * file.cc (class1::function1): Make change foo.
      (class2::function2): Make change bar.


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


maint: Merge stable to default.
For style points, please also write "New function" instead of "Added function" or "Return retval" instead of "Changed to return retval".
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).


== Guidelines ==
And please, never "Fixed bug" or similar. That doesn't add any specific information about what was changed.


The general structure of a commit message should be clear from the examples:
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.


* After the first line, leave one blank line.
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.
* 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. <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.


== Examples ==


=== Wording ===
* standard commit messages
<pre>
allow abbreviations for optimset and optimget (bug #38999)


{| class="wikitable"
* optimset.m, optimget.m: Handle abbreviated keys and warn for
! bad
ambiguous abbreviations. New tests.
! good
</pre>
|-
<pre>
| style="color:darkred;" | "Added function"
add format option to ticklabel (bug #34906)
| style="color:green;" | "New function"
|-
| style="color:darkred;" | "Changed to return retval"
| style="color:green;" | "Return retval"
|-
| style="color:darkred;" | "Fixed bug"
| style="color:green;" | 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.
* graphics.cc: add new functions to support different input arguments to
  xyzticklabel. Add tests.
* graphics.in.h: define set_xyzticklabel as external function
</pre>
<pre>
tag symbols in indexed assignments as variables (bug #39240)


=== Body of the commit message ===
* pt-arg-list.cc (tree_argument_list::variable_names): Also return the
 
  symbol names from index expressions.
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
* parser.tst: New test.
 
</pre>
* 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 {{codeline|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 short and very simple commit messages under 80 characters.  
<pre>@ftp/cd.m: Fix docstring.</pre>
<pre>strjoin.m: delimiter can include escape sequences (matlab compatibility)</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.
* 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:

Retrieved from "https://wiki.octave.org/Commit_message_guidelines"