296
edits
Commit message guidelines: Difference between revisions
Jump to navigation
Jump to search
→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 | ||
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): | * file.cc (class1::function1): Add something. | ||
( | (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- | <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 === | ||