mirror of
git://sourceware.org/git/libabigail.git
synced 2024-12-14 22:14:35 +00:00
80e78b22e1
Explain how ChangeLog entries need to refer to each modified function. Also, give more information more about the expected spirit of the commit log. * COMMIT-LOG-GUIDELINES: Various enhancements. Signed-off-by: Dodji Seketeli <dodji@redhat.com>
130 lines
4.9 KiB
Plaintext
130 lines
4.9 KiB
Plaintext
Git commit messages format
|
|
==========================
|
|
|
|
The principle of the git commit log is to document at least the
|
|
*what*; in English. That is redundant with the commit diff, yes. But
|
|
that redundancy does help in understanding the commit diff better. If
|
|
appropriate, the commit log can also document the *why*, but only if
|
|
it does so by respecting the format of the commit log. The reason why
|
|
we are so strict about the format is that the commit log is later
|
|
parsed by a tool to build a ChangeLog, which we want to stay compliant
|
|
with the GNU ChangeLog format.
|
|
|
|
So here is the format we are talking about.
|
|
|
|
The first line of a git commit message should start at column 1, with
|
|
no space. That line should be a short summary of the purpose of the
|
|
commit. If the commit relates to a bug filed into bugzilla, the line
|
|
should begin with the bug (or Problem Report) number, followed by a
|
|
white space; e.g:
|
|
|
|
Bug <number-of-the-bug> This is a great commit
|
|
|
|
The line in its entirety should not be longer than 50 characters.
|
|
|
|
The next line should be an empty line, with no spaces.
|
|
|
|
Subsequent lines can be a free form introductory text that should
|
|
start column 0. The introductory text can have an arbitrary number of
|
|
lines. No line in that text should start with the sequence
|
|
<white-space>*. That is, no line in that text should start with a
|
|
sequence of white spaces followed by the start character (*).
|
|
|
|
If there was an introductory text, then the next line should be an
|
|
empty line, with no spaces.
|
|
|
|
The subsequent lines should have the form of the Body of a GNU ChangeLog
|
|
entry, i.e:
|
|
|
|
* file1.c (func1): Changed foo in this function.
|
|
(func2): Changed blah in that function
|
|
* file2.c (func_foo): Changed something here.
|
|
|
|
Note that before the '*', there is a tab that is 8 spaces long. Also
|
|
note that right after the '*', there is a space.
|
|
|
|
An example of commit message would be:
|
|
|
|
~=~
|
|
Bug 123456 Add super feature
|
|
|
|
The super feature requires modifying function_bleh to make it call
|
|
function_foo instead of function_bar. As function_bar is no more
|
|
used, this patch removes it.
|
|
|
|
* file1.c (function_foo): Define new static function.
|
|
* file2.c (function_bar): Removed static function.
|
|
* file3.c (function_bleh): Modified this function to call
|
|
function_foo, rather than function function_bar.
|
|
~=~
|
|
|
|
Note how, in the ChangeLog part of the commit log, each function
|
|
modification is mentioned, by referring to the name of the function in
|
|
parenthesis. The length of a line should not exceed 72 characters.
|
|
The description of what happens to the function should be succinct.
|
|
Just describe the "what".
|
|
|
|
The "how" should be described by comments in the code change itself,
|
|
so there is no need to describe in the ChangeLog part of the commit
|
|
log.. The "why" and "general spirit" of the change should be
|
|
described in the introductory text that precedes the ChangeLog part.
|
|
So, again, no need to add to the ChangeLog part.
|
|
|
|
For files that contain no function definitions, the ChangeLog looks
|
|
like:
|
|
|
|
~=~ Bug 123456 Shorten compilation lines
|
|
|
|
* configure.ac: Shorten compilation lines by regrouping
|
|
PKG_CHECK_MODULES calls.
|
|
* tests/Makefile.am: Adjust this.
|
|
~=~
|
|
|
|
Another one could be:
|
|
|
|
~=~
|
|
Bug 123456 Shorten compilation lines
|
|
|
|
Blah blah, this is an introductory text explaining the purpose of this
|
|
commit. It can contain whatever character I want. It just cannot
|
|
contain a line that starts with white spaces immediately followed by
|
|
the star character.
|
|
|
|
* configure.ac: Shorten compilation lines by regrouping
|
|
PKG_CHECK_MODULES calls.
|
|
* tests/Makefile.am: Adjust this.
|
|
~=~
|
|
|
|
When it's needed, the introductory text is very important. Please
|
|
take time to explain the current status of the code (before your
|
|
patch) and why it was in the need of your patch. In other words, take
|
|
time to explain the problem you are trying to solve. If the problem
|
|
is explained in a bug in the bugzilla, please try to explain it again,
|
|
using your words. Just linking to the bugzilla is generally not
|
|
enough. And then, yes, refer to the bugzilla.
|
|
|
|
Then explain how your changes address the issue that you've just
|
|
described.
|
|
|
|
In other words, the introductory text should tell a story. So please
|
|
be generous :-)
|
|
|
|
And then the ChangeLog part of the commit log is another exercise.
|
|
This one has to be succinct. Every single function or global variable
|
|
or type changed (or added/removed) has to be mentioned explicitly by
|
|
name as shown in one of the examples above.
|
|
|
|
Writing the ChangeLog part of the commit log can seem tedious, but
|
|
it's an excellent way to perform an auto-review of your work. You'd
|
|
be surprised by the number of issues that you catch in the process.
|
|
|
|
Also, please keep in mind that reviewers of the code are going to do a
|
|
function-by-function and line-by-line review of your changes, so
|
|
please, take the time to do so as well. This is a great way to give
|
|
great quality to your code.
|
|
|
|
We encourage you to look at the existing commit logs or at the
|
|
ChangeLog file for inspiration.
|
|
|
|
Happy Hacking!
|