Commit style
A few advises and rules about commit messages
The overall format for git commits is as follows:
component1, component2: imperative description of the change
Detailed or technical description of the change and what motivates it,
if it is not entirely obvious from the title.
- the commit message, just like the code, must be in english (only ASCII characters for the title)
- there can be multiple components separated by
:
in case of hierarchical relationships, with,
otherwise - components are lower-case, using
-
,_
or.
if necessary - the imperative description of the change begins with a lower-case verb
- the title must not contain any link (
#
is forbidden)
Ideally:
- the title should be self-explanatory: no need to read anything else to understand it
- the commit title is all lower-case
- the title is clear to a reader not familiar with the code
- the body of the commit contains a detailled description of the change
An automated check is performed to enforce as much as possible this formating.
Counter-examples of commit titles
To be avoided entirely:
component: update ./some/file.ext
: specify the update itself rather than the file, the files are technical elements welcome in the body of the commitcomponent: fix #42
: specify the problem fixed in the title, links (to issue, etc.) are very welcome in commit’s bodywip
: describe the work (and finish it)
Welcome to ease review, but do not merge:
fixup! previous commit
: an autosquash must be run before the mergeRevert "previous commit of the same PR"
: both commits must be dropped before merging