Commit message guidelines: Difference between revisions

→‎Body of the commit message: clarify and expand with more specific exceptions
(→‎One-line description: reword for clarity, add build prefix)
(→‎Body of the commit message: clarify and expand with more specific exceptions)
Line 47: Line 47:


If there is more than one file touched in different ways and the one-line
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
description isn't enough to describe all changes, the commit message needs a
a full-body description.
full-body description.


Individual files you touched get their changes separately enumerated. If
Each individual file changed by a commmit must have its changes enumerated.
there a particular C or C++ function you changed, the general format is
For changes affecting specific C++ functions, each function name is listed in
parentheses. For example


<pre>
<pre>
* file.cc (class1::function1): Make change foo.  
* file.cc (class1::function1): Add something.
(class2::function2): Make change bar.
(function2, function3): Delete something else.
</pre>
</pre>


Note the newline for describing the change to a different function. General
For changes affecting specific Octave built-ins, each built-in name is listed
GNU style guidelines can be followed here, so that similar changes to
in parentheses with an "F" prefix, an implementation detail. For example
different files can be grouped.


For m-script and Fortran sources, the function name can be omitted if
<pre>
the m-script only contains one file. For changes outside of functions
* data.cc (Fcolumns): Return columns.
or classes, of course the parenthetical (function) or (class::function)
</pre>
specifiers can also be omitted.
 
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>
 
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 ===
296

edits