mirror of
git://sourceware.org/git/libabigail.git
synced 2024-12-21 01:09:59 +00:00
71aba18621
* gen-changelog.py (process_commit): Everything that comes between the subject line of the commit and the first \t* sequence is considered to be introductory text. Ignore it when generating the ChangeLog entry. * COMMIT-LOG-GUIDELINES: Update the commit log guidelines to reflect the fact that we can now have introductory text in the commit log. Signed-off-by: Dodji Seketeli <dodji@redhat.com>
74 lines
2.5 KiB
Plaintext
74 lines
2.5 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:
|
|
|
|
PR <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 exemple of commit message would be:
|
|
|
|
~=~
|
|
PR 123456 Shorten compilation lines
|
|
|
|
* configure.ac: Shorten compilation lines by regrouping
|
|
PKG_CHECK_MODULES calls.
|
|
* tests/Makefile.am: Adjust this.
|
|
~=~
|
|
|
|
Another one could be:
|
|
|
|
~=~
|
|
PR 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.
|
|
~=~
|
|
|
|
|
|
We encourage you to look at the existing commit logs or at the
|
|
ChangeLog file for inspiration.
|