Guidelines for Commit Messages

Those are only recommended guidelines and maintainers can feel free to adopt other guidelines.

Reasoning

A more extensive documentation in line with the GNOME commit style including reasoning is available at http://coala.io/commit .

Example

tag: Short explanation of the commit

Longer explanation explaining exactly what's changed and why, whether
any external or private interfaces changed, what issue were fixed (with
issue number if applicable) and so forth. Be concise but not too brief.

Fixes #123456.

Details

• The commit message is mainly for the other people, so they should be able to understand it now and six months later.

• Always add a brief description of the commit to the first line of the commit and terminate by two newlines (it will work without the second newline, but that is not nice for the interfaces).

• First line (the brief description) must only be one sentence and should start with a capital letter unless it starts with a lowercase symbol or identifier. Don't use a trailing period either. It's recommended to not exceed 50 characters but it's not always possible/easy to follow this limit. In any case, don't exceed 72 characters.
• You can prefix the first line with one tag, to make it easier to know to which part of the module the commit applies. For example, a commit with "fish: Make it work with newer fortune" in the gnome-panel module clearly applies to the fish applet.
• The description part (the body) is normal prose and should use normal punctuation and capital letters where appropriate. Normally, for patches sent to a mailing list, the body is copied from there. This description part can be empty if the change is self-explanatory (eg: "Add DOAP file").
• Each line in description must not exceed 75 characters (there is no limit on number of lines).

• When committing code on behalf of others use the --author option, e.g. git commit -a --author "Joe Coder <joe@coder.org>".

• If this commit is related to an issue on gitlab.gnome.org, include a link to the issue at the bottom of the commit message, with one blank line above it.
• Use imperative form of verbs rather than past tense when referring to changes introduced by commit in question. For example "Remove property X" rather than "Removed property X".

Checklist

It is very easy for developers (especially newcomers) to forget about the above points so its better to always go through this checklist for each patch before filing a merge-request:

• Summary line:
  • Be sure to not exceed 72 characters. Try to not exceed 50.
  • Use present tense. For example use "Add Hindi translation" instead of "Added Hindi translation".
  • Summarize the change itself in the shortlog, not the issue or effects/benefits (that goes in description).
  • Leave out the trailing period (full stop).

  • You can use '&' instead of 'and' so the message gets shorter.

  • You can add a tag in lower cases with a colon before the rest.
  • Describe it for everyone, not just for you.
  • Add a blank line after it.
• Description:
  • Each line must not exceed 75 characters.
  • You may leave out the description if the summary is self-explanatory.
  • Use normal language and punctuation here.
  • If the commit relates to an issue, don't forget to reference it using "#ISSUE_NUMBER" syntax.
  • If the commit fixes an issue, add a line on the last paragraph: "Fixes #ISSUE_NUMBER.".
• General:
  • Give other users the credit they deserve. You would probably expect the same from others. (--author)

  • If you use git revert command to undo a commit, git generates a default commit message specifying the hash and commit message of the commit you're undoing, but this is not enough to know *why* you're reverting it, so please add more comments to it.

  • Set git to use a good editor by running git config --global core.editor EDITOR. Simple editors like nano make it hard to create well formatted messages. Editors like vim or emacs will add highlighting and automatic word wrapping making it a lot easier to write well formatted commit messages.