Git Commit Policy

Why do we need one?

Well:

1. Everyone commits in different ways and it makes it harder to follow what's going on if different formats are used.
2. We want to automate releases a bit more using a format we can script to save time during the week.

Policy

General

• Usually a commit includes the area of Tracker which changes as a prefix to the change itself.

  • For test cases which also change something related to a binary we don't use tests: instead we use the binary which is being tested and refer to the test in the commit.

  • e.g. If referring to the tracker-miner-fs binary we need to know that for the release notes and so use:

    commit 7a1cbd264dc125a9abaa1d8d7b28956bc6eb0e1c
    Author: Aleksander Morgado <aleksander@lanedo.com>
    Date:   Wed Dec 1 11:23:31 2010 +0100
    
        tracker-miner-fs: Use tracker_file_is_hidden()

• The title of the commit shouldn't be so long that it doesn't fit within 80 characters if possible.
• Avoid useless titles that tell other developers on the team nothing about the change:

  • e.g. tracker-store: fixed bug <-- What?

  • e.g. tracker-store: fixed memory leak <-- Where?

Bug Fixes

All commits which fix a bug in Bugzilla somewhere should:

• Include the bug number in the body of the commit, not the title.

• The format should be Fixes GB#123456 as a minimum. The GB part refers to the Bugzilla hosting the bug used in scripts to retrieve the actual description of the bug for NEWS updates during a release. For now, we use:

  • GB: GNOME Bugzilla (http://bugzilla.gnome.org)

  • NB: Nokia Bugzilla (https://projects.maemo.org/bugzilla)

  • MG: MeeGo Bugzilla (http://bugs.meego.com/)

Changes showing up in the NEWS & Release Notes

Our release scripts look for [NEWS] in each commit message body to know if it should be added to the NEWS file and release notes. There are some guidelines for this:

• The title of the commit is used in the NEWS & release notes

• The body of the commit must include [NEWS]

  • e.g.

    commit dd413866582f89b7b249596d4da78d3794df724d
    Author: Martyn Russell <martyn@lanedo.com>
    Date:   Fri Jan 15 15:45:56 2010 +0000
    
        tracker-search: Warn about using stopwords as search terms
    
        [NEWS]

• The title must not be cryptic to non-Tracker developers.

  • e.g. tracker-extract: Support MP3 files <-- good

  • e.g. tracker-extract: Propagate radio waves through a sheep's bladder for efficiency <-- bad

• Avoid trivial issues.

  • e.g. tracker-extract: Whitespace clean up

• Major changes must be added with the [NEWS] keyword.

  • e.g. Requires Vala 0.11.2 was 0.11.1