Git Commit Policy
Why do we need one?
- Everyone commits in different ways and it makes it harder to follow what's going on if different formats are used.
- We want to automate releases a bit more using a format we can script to save time during the week.
- 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 <email@example.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?
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:
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]
commit dd413866582f89b7b249596d4da78d3794df724d Author: Martyn Russell <firstname.lastname@example.org> 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