Changes

Jump to navigation Jump to search

Commit message guidelines

473 bytes added, 10:51, 24 August 2016
add more examples and explanation from the manual
hg log --style changelog >> octave_changelogs.log
 
== Guidelines ==
 
General structure of a commit message:
 
:: '''One-line description'''
:: ''Empty line''
:: '''Body of the commit message'''
Each part is explained in detail below. Here there is an example:<pre>Give message id to undefined function error=== One-line description ===
* ptThe commit message should have a brief a one-idline description of what thecommit does. Keep it short, preferably under 80 characters. If you arepatching a bug, this one-line explanation should mention the bug numberat the end like so: {{codeline|... (bug #12345)}}.cc Omit final period (tree_identifier::eval_undefined_errorfull stop): used ::error_with_id instead of ::error to report undefined functions with id.</pre>
=== OneIf your change only touches one file, then the filename of that file shouldbe the prefix of the one-line description === . If it's a C++ or C file, thefunction or class that is being modified should be included in theparenthetical remark, as in the full body of the commit message.
The commit message has a one-line description. Keep it short, preferrably under 80 characters. If you're squashing a bug, the bug number you're squashing should be included in this one-line description, like so at the end: <tt>(bug #12345)</tt>. Omit final period (full stop). Sometimes the one-line description is sufficient, for small changes. In that caseaddition, we use the following there are two prefixes to give a description of what the small change isfor special commits:
* maint: for reorganisation of the sources that do not change the source. Regular merge commits are a prominent example.
* doc: for changes to the documentation.
If your change is small and only touches one file, then the filename of that file should be the prefix of the one-line description. If it's a C++ or C file, the function or class that this is being modified should be included in the parenthetical remark, as in the full body of the commit messagetypically sufficient.
=== Body of the commit message ===
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 a full-body description. Individual files you touched get their changes separately enumerated. Ifthere a particular C or C++ function you changed, the general format is <pre>* file.cc (class1::function1): Make change foo. (class2::function2): Make change bar.</pre>
Individual files you touched get their changes separately enumerated. If there Note the newline for describing the change to a particular C or C++ different function you changed. GeneralGNU style guidelines can be followed here, the general format isso that similar changes todifferent files can be grouped.
* For m-script and Fortran sources, the function name can be omitted ifthe m-script only contains one file.cc For changes outside of functionsor classes, of course the parenthetical (class1::function1function): Make change foo. or (class2class::function2function): Make change barspecifiers can also be omitted.
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.=== Wording ===
For style points, please also Please write "New function" instead of "Added function" or "Return retval" instead of "Changed to return retval".
And please, never Never write "Fixed bug" or similar. That doesn't add any specific information about what was changed.
The changelog info in the commit message should say describe what was changed, not whyit was changed. If you need to explain Any explanation for why, that info a change is needed should probably go in appear as comments in the code, particularly if there is something that might not be obvious to someonereading it later.
For m-script and Fortran sources, the function name can be omitted if the m-script only contains one file. For changes outside of functions or classes, of course the parenthetical (function) or (class::function) specifiers can also be omitted.
== Examples ==
<pre>look for methods before constructors * standard commit messagessymtab.cc (symbol_table::fcn_info::fcn_info_rep::find):Look for class methods before constructors, contrary to Matlabdocumentation.* test/ctor-vs-method: New directory of test classes.* test/test_ctor_vs_method.m: New file.* test/Makefile.am: Include ctor-vs-method/module.mk.(FCN_FILES): Include test_ctor_vs_method.m in the list.</pre> 
<pre>
allow abbreviations for optimset and optimget (bug #38999)
ambiguous abbreviations. New tests.
</pre>
 
<pre>
add format option to ticklabel (bug #34906)
* graphics.in.h: define set_xyzticklabel as external function
</pre>
 
<pre>
tag symbols in indexed assignments as variables (bug #39240)
</pre>
* For short === One line commit examples === This examples are the rare cases where only one file is modified and very thechange is simple commit messages under 80 charactersenough: <pre>maint: merge away accidental head.</pre><pre>maint: Strip trailing whitespace from source files.</pre><pre>maint: Update gnulib to latest changes. </pre><pre>@ftpmaint: Periodic merge of stable to default.</cdpre><pre>doc: grammarcheck documentation for 4.2 release.</pre><pre>pkg.mm4: Fix docstringupdate to lastest version as released with pkg-config 0.29 (bug #48775)</pre><pre>strjoinuigetfile.m: delimiter can include escape sequences allow path names as input arg (matlab compatibilitybug #48828)</pre>
* maintenance or docs commits, no actual code changed
<pre>maint: update config.in.h in .hgignore</pre>
[[Category:Development]]

Navigation menu