Changes

Jump to navigation Jump to search
1,072 bytes added ,  23:26, 12 March 2020
→‎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

Navigation menu