296
edits
Changes
Jump to navigation
Jump to search
Line 47:
Line 47: − + − 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+ + − + − + − 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. − + − the m-script only contains one file. For changes outside of functions+ − + − + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
→Body of the commit message: clarify and expand with more specific exceptions
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
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>
<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>
For changes affecting specific Octave built-ins, each built-in name is listed
in parentheses with an "F" prefix, an implementation detail. For example
For m-script and Fortran sources, the function name can be omitted if
<pre>
* 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 ===