wiki.ipfire.org

The community-maintained documentation platform of IPFire

User Tools

Site Tools


devel:git:commit-messages

Commit message and patch format

It is very important to conform to this as best as you can. The commit message is an essential part of a change that is integrated into IPFire as it will be kept in the history of the project for ever. Sometimes you stumble across them after years and even then everyone who reads it needs to be able to understand what a change is doing.

We have this guidelines that you find below and strongly advice for follow them as best as possible to increase the change that your patch will get accepted.

How to write a good commit message?

What to take care of?

Describe your changes

Describe your changes in imperative mood, e.g. “make abc do xyz” instead of “[This patch] makes abc do xyz” or “[I] changed abc to do xyz”, as you are giving orders to the code base to change its behaviour.

It does not matter if your patch is a one-line bug fix or a couple of thousand lines patch of a new feature. At all times it is required to accurately describe the underlying problem that motivated you to work on this patch. Convince the reviewer that there is a problem worth fixing and that it makes sense for them to read past the first paragraph.

Describe the impact of your change. Are there any user-visible changes? Straight up crashes and lockups are pretty convincing, but not all bugs are that blatant. Even if the problem was spotted during code review, describe the impact that you think it can have on users.

Quantify optimisations and trade-offs. If you claim improvements in performance, memory consumption, or similar, include numbers that back them up. But also describe non-obvious costs. Describe the expected downsides of your optimisation so that the reviewer can weigh costs against benefits.

Describe how you solved the problem

Once the problem is established, describe what you are actually doing about it in technical detail. It is import to describe the change in plain English for the reviewer to verify that the code is behaving as you intend it to.

Make sure that your description complies with the general commit guidelines and is formatted appropriately.

Solve only one problem in a patch. If your description is getting long, that is a sign that you should probably split up your patch.

Re-sending patches

When you resubmit a patch or patch series, include the complete patch description and justification for it. Don't just say that this is version N of the patch (series). Don't expect the maintainer to refer back to earlier patch versions or referenced URLs to find the patch description and put that back into the patch. The patch and its description should be self-contained at all times.

Add references & external resources

If the patch fixes a logged bug entry, refer to that bug entry by its number. If the patch follows from a mailing list discussion, give a URL to the mailing list archive; use http://lists.ipfire.org.

However, try to make your explanation understandable without external resources. In addition to giving a URL to a mailing list archive or bug, summarize the relevant points of the discussion that led to the patch as submitted.

You should always include 12 characters of the SHA-1 commit ID when referring to other commits and also include the first line. The following git-config settings can be used to add a pretty format for outputting the above style in the git log or git show commands

[core]
  abbrev = 12
[pretty]
  fixes = Fixes: %h (\"%s\")

The canonical patch format

This section describes how patches itself should be formatted. Note that, if you have your patches stored in a git repository, proper patch formatting can be had with “git format-patch”. The tools cannot create the necessary text, though. See above for instructions about that.

The canonical patch subject line is:

Subject: [PATCH 001/123] package: summary phrase

The canonical patch message body contains the following:

  • A “From” line specifying the patch author (only needed if the person sending the patch is not the author)
  • An empty line
  • The body of the explanation, which will be copied to the permanent changelog to describe this patch.
  • The “Signed-off-by:” lines, which will also go in the changelog.
  • A marker line containing simply “—”.
  • Any additional comments not suitable for the changelog.
  • The actual patch (diff output).

The Subject line format makes it very easy to sort the emails alphabetically by subject line - pretty much any email reader will support that - since because the sequence number is zero-padded, the numerical and alphabetic sort is the same.

devel/git/commit-messages.txt · Last modified: 2015/05/05 13:42 by MichaelTremer