For Developers: Commit Messages

The goal of a commit message is to communicate the motivation and mechanics of a change. It provides the context required for others to review the patch for correctness. It will also provide breadcrumbs to your future self if the commit later has to be debugged. As always, common-sense is key to writing a good message. Some changes are so obvious or trivial that they can be described in a single sentence: the code itself does most of the talking. Other changes are so subtle or extensive that a longer block of plain English is helpful to explain "why" the patch is necessary and "how" it works.

Examples

To see some real-world examples of high-quality commit messages with good formatting and sign-off statements, see any recent Linux kernel changelog (e.g. https://cdn.kernel.org/pub/linux/kernel/v5.x/ChangeLog-5.4.138). One example from our own driver is reproduced below:

HID: wacom: support named keys on older devices

Some Wacom devices have keys with predefined meanings. However, when
support was originally added for these devices, the codes for these
keys were not available yet. These keys were thus reported with
the numbered KEY_PROG* range.

Some missing key codes were added with commit 4eb220cb35a9 ("HID:
wacom: generic: add 3 tablet touch keys") and we are now able to
report the proper key codes. We continue to report the original
KEY_PROG codes so as not to break any unknown applications that
may depend on them.

Also, to support the touch key, track its state in the pad report.

Signed-off-by: Aaron Armstrong Skomra <[email protected]>
Link: https://gitlab.freedesktop.org/libinput/libinput/merge_requests/155
Link: https://github.com/linuxwacom/xf86-input-wacom/pull/46
Reviewed-by: Ping Cheng <[email protected]>
Reviewed-by: Jason Gerecke <[email protected]>
Signed-off-by: Jiri Kosina <[email protected]>

Formatting

Commit messages should be styled to follow a standard format. This format consists of a one-line summary, one or more paragraphs of description, and a "sign-off" section at the end. Lines should be wrapped to be ~72 characters in length if possible. A single blank line should separate individual paragraphs and sections.

• The commit summary should be a short but accurate description of the change. It may optionally start with one or more 'prefixes' (e.g. "HID: ", "tools: ", "xsetwacom: ") to highlight changes to a particular subsystem.

• The commit description should explain (at an appropriate level of detail) what is being changed, why the change is necessary, and how the new code code works.

• The sign-off section will contain other patch metadata. A Signed-off-by tag is required at minimum, but other data may also be provided if relevant (see "Signing off your patch" below).

If you are handling a patch on behalf of another person (e.g. backporting a patch from upstream, merging a patch from someone else, etc.) you should generally avoid making changes to it. You may safely append your own sign-off tags to the very end (please do not insert new tags in the middle of an existing sign-off section) as a final action, however.

Signing off your patch

The end of every commit message should have a "sign-off section" which contains additional metadata in a standardized form. At minimum this section should have a Signed-off-by tag, but it is encouraged to add other tags which may be relevant. For example, if your patch fixes a bug, include the hash and patch title of the patch you are fixing in your commit message along with a link to any relevant bug reports. If this is Linux kernel patch that fixes a bug, you may also want to CC stable with the earliest version of the kernel that contains this bug.

The following is an example of a sign-off section with a few different tags:

Signed-off-by: Ada Lovelace <[email protected]>
Fixes: c7f0522a1ad1 ("HID: wacom: add Intuos 42 support")
Link: https://github.com/linuxwacom/input-wacom/issues/4243
Cc: <[email protected]> # v4.5+

Here is a list of common tags and their meanings:

Tag	Meaning
Signed-off-by: Adam Apple <[email protected]>	Certifies that the named person wrote this patch or otherwise has the right to pass it on as a open-source patch.
Acked-by: Bella Blue <[email protected]>	Certifies that the named person approves of the patch but has not spent significant time reviewing/testing it.
Reviewed-by: Cooper Clay <[email protected]>	Certifies that the named person has read through the patch in detail and believes it to be correct.
Tested-by: Dianne Dunn <[email protected]>	Certifies that the named person has tested the patch and did not encounter any bugs.
Reported-by: Edgar Elm <[email protected]>	Provides credit to the named person for finding the issue resolved by this patch.
CC: Freida Flynn <[email protected]>	Indicates another person who should be (automatically) notified when the patch is sent.
CC: <[email protected]> #vX.Y+	Indicates that the patch should be automatically backported to the "X.Y" and newer "stable" kernels.
Fixes: abcdef012345 ("Full commit title")	Provides a reference to the ID and title of the commit which introduced the bug that this commit fixes.
Link: https://some.url/issue/12345	Provides a link to the bug report that was filed for the issue fixed by this commit.

For more information on signing-off your patch, and making patches in general, see the kernel guidelines.