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:

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

Projects/Tracker/Documentation/GitCommitPolicy (last edited 2013-11-25 12:54:23 by WilliamJonMcCann)