Octave

Commit message guidelines: Difference between revisions

Page Discussion

Commit message guidelines (edit)

Revision as of 07:45, 10 June 2020

857 bytes removed ,  10 June 2020
no edit summary
No edit summary
Line 6: Line 6:


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].
== Guidelines ==
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.
=== 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>
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>
* data.cc (Fcolumns): Return columns.
</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>
* file1.cc, file2.cc, file3.cc, file4.cc: Include <sys/types.h>.
* memory.cc (function1, function2, function3): Throw error if empty.
</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>
* file.cc (function1): Add an option.  (function2): Add another option.
</pre>
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
<pre>
* 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
files affected by a change, even when they have the same name with different
file extensions. For example
<pre>
* oct-fftw.cc, oct-fftw.h (octave_fftw_version): New function.
</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.
=== Wording ===
{| class="wikitable"
! bad
! good
|-
| style="color:darkred;" | "Added function"
| 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.


== Examples ==
== Examples ==
Line 162: Line 52:
</pre>
</pre>


=== One line commit examples ===
=== One line examples ===


This examples are the rare cases where only one file is modified and the change is simple enough:
This examples are the rare cases where only one file is modified and the change is simple enough:
Line 179: Line 69:
   
   
  uigetfile.m: allow path names as input arg (bug #48828)
  uigetfile.m: allow path names as input arg (bug #48828)
== Guidelines ==
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. <code>(bug #12345)</code>, where applicable.
* Use prefixes where applicable:
** <code>maint:</code> for reorganisation of the sources that do not change the source. Regular merge commits are a prominent example.
** <code>doc:</code> for changes to the documentation.
** <code>build:</code> for changes to the build system, for example autoconf or automake files.
=== Body of the commit message ===
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 {{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 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 ===
{| class="wikitable"
! bad
! good
|-
| style="color:darkred;" | "Added function"
| 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.




[[Category:Development]]
[[Category:Development]]
Retrieved from "https://wiki.octave.org/Special:MobileDiff/13134"