COMMIT-LOG-GUIDELINES

   1 Git commit messages format
   2 ==========================
   3
   4 The principle of the git commit log is to document at least the
   5 *what*; in English.  That is redundant with the commit diff, yes.  But
   6 that redundancy does help in understanding the commit diff better.  If
   7 appropriate, the commit log can also document the *why*, but only if
   8 it does so by respecting the format of the commit log.  The reason why
   9 we are so strict about the format is that the commit log is later
  10 parsed by a tool to build a ChangeLog, which we want to stay compliant
  11 with the GNU ChangeLog format.
  12
  13 So here is the format we are talking about.
  14
  15 The first line of a git commit message should start at column 1, with
  16 no space. That line should be a short summary of the purpose of the
  17 commit.  If the commit relates to a bug filed into bugzilla, the line
  18 should begin with the bug (or Problem Report) number, followed by a
  19 white space; e.g:
  20
  21 Bug <number-of-the-bug> This is a great commit
  22
  23 The line in its entirety should not be longer than 50 characters.
  24
  25 The next line should be an empty line, with no spaces.
  26
  27 Subsequent lines can be a free form introductory text that should
  28 start column 0.  The introductory text can have an arbitrary number of
  29 lines.  No line in that text should start with the sequence
  30 <white-space>*.  That is, no line in that text should start with a
  31 sequence of white spaces followed by the start character (*).
  32
  33 If there was an introductory text, then the next line should be an
  34 empty line, with no spaces.
  35
  36 The subsequent lines should have the form of the Body of a GNU ChangeLog
  37 entry, i.e:
  38
  39         * file1.c (func1): Changed foo in this function.
  40         (func2): Changed blah in that function
  41         * file2.c (func_foo): Changed something here.
  42
  43 Note that before the '*', there is a tab that is 8 spaces long.  Also
  44 note that right after the '*', there is a space.
  45
  46 An example of commit message would be:
  47
  48 ~=~
  49 Bug 123456 Add super feature
  50
  51 The super feature requires modifying function_bleh to make it call
  52 function_foo instead of function_bar.  As function_bar is no more
  53 used, this patch removes it.
  54
  55         * file1.c (function_foo): Define new static function.
  56         * file2.c (function_bar): Removed static function.
  57         * file3.c (function_bleh): Modified this function to call
  58         function_foo, rather than function function_bar.
  59 ~=~
  60
  61 Note how, in the ChangeLog part of the commit log, each function
  62 modification is mentioned, by referring to the name of the function in
  63 parenthesis.  The length of a line should not exceed 72 characters.
  64 The description of what happens to the function should be succinct.
  65 Just describe the "what".
  66
  67 The "how" should be described by comments in the code change itself,
  68 so there is no need to describe in the ChangeLog part of the commit
  69 log..  The "why" and "general spirit" of the change should be
  70 described in the introductory text that precedes the ChangeLog part.
  71 So, again, no need to add to the ChangeLog part.
  72
  73 For files that contain no function definitions, the ChangeLog looks
  74 like:
  75
  76 ~=~ Bug 123456 Shorten compilation lines
  77
  78         * configure.ac: Shorten compilation lines by regrouping
  79         PKG_CHECK_MODULES calls.
  80         * tests/Makefile.am: Adjust this.
  81 ~=~
  82
  83 Another one could be:
  84
  85 ~=~
  86 Bug 123456 Shorten compilation lines
  87
  88 Blah blah, this is an introductory text explaining the purpose of this
  89 commit.  It can contain whatever character I want.  It just cannot
  90 contain a line that starts with white spaces immediately followed by
  91 the star character.
  92
  93         * configure.ac: Shorten compilation lines by regrouping
  94         PKG_CHECK_MODULES calls.
  95         * tests/Makefile.am: Adjust this.
  96 ~=~
  97
  98 When it's needed, the introductory text is very important.  Please
  99 take time to explain the current status of the code (before your
 100 patch) and why it was in the need of your patch.  In other words, take
 101 time to explain the problem you are trying to solve.  If the problem
 102 is explained in a bug in the bugzilla, please try to explain it again,
 103 using your words.  Just linking to the bugzilla is generally not
 104 enough.  And then, yes, refer to the bugzilla.
 105
 106 Then explain how your changes address the issue that you've just
 107 described.
 108
 109 In other words, the introductory text should tell a story.  So please
 110 be generous :-)
 111
 112 And then the ChangeLog part of the commit log is another exercise.
 113 This one has to be succinct.  Every single function or global variable
 114 or type changed (or added/removed) has to be mentioned explicitly by
 115 name as shown in one of the examples above.
 116
 117 Writing the ChangeLog part of the commit log can seem tedious, but
 118 it's an excellent way to perform an auto-review of your work.  You'd
 119 be surprised by the number of issues that you catch in the process.
 120
 121 Also, please keep in mind that reviewers of the code are going to do a
 122 function-by-function and line-by-line review of your changes, so
 123 please, take the time to do so as well.  This is a great way to give
 124 great quality to your code.
 125
 126 We encourage you to look at the existing commit logs or at the
 127 ChangeLog file for inspiration.
 128
 129 Happy Hacking!