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 === |