Commit messages on trunk

[Gustavo Niemeyer]

Greetings developers (and potential candidates),

After a quick inspection in our current history for the trunk branch:

    http://bazaar.launchpad.net/~ensemble/ensemble/trunk/changes

It seems that one healthy practice regarding commit messages that we
used to have has been a bit lost in time, and it would be nice to have
it back.

Specifically, commit messages to trunk should follow a specific format
which inform: the branch merged, the reviewer, the bug number, and a
user oriented explanation of what the branch benefit is.  This is
important because it gives a nice history not only for ourselves, but
also for users which are watching and trying to make sense of how the
project is evolving.

Here is an example, from the development guideline:

    Merged hidden-tetris [r=jkakar,radix] [f=73462].

    It is now possible for users named Bob to play a javascript version of
    Tetris by clicking on a pixel in the upper-right corner.


Here is the full section:


=== Writing log messages ===

Whenever creating log messages, try to concisely explain what was
done in the change, and if possible how.  Do that by looking at the
''diff'' of changes being committed.

When there are multiple log entries, use dashes to preceed each
entry, as follows:
{{{
- Capitalized sentences in --help.
- Renamed Class.foo to Class.bar.
}}}

If you have a very long list of items, it's a hint that you should
try to commit more often.

If you're in doubt about whether a change should be mentioned in the
log or not, that's an indication that it should.

When doing '''changes in trunk''' include the following markers at the
end of the first line of the log message, when sensible:

|| '''Marker''' || '''Meaning''' ||
|| `[r=radix,jkakar]` || Branch was reviewed by Chris and Jamu. ||
|| `[a=jkakar]` || Branch was authored by Jamu (use only when merging
someone else's branch). ||
|| `[trivial]` || Changes being integrated are trivial. ||
|| `[f=1234,3456]` || Fixes bugs #1234 and #3456. ||

A prosaic, high-level description of the feature or bugfix your branch
makes should be included as well. This should not be a duplication of
the individual commit messages in the branch, but something which
describes ''what'' the branch does, in terms that would make sense to
someone who read and understands the original bug report/feature
request. Consider the issue in the tracker the question, and your
commit message the response.

Here is a log message example:
{{{
Merged hidden-tetris [r=jkakar,radix] [f=73462].

It is now possible for users named Bob to play a javascript version of
Tetris by clicking on a pixel in the upper-right corner.
}}}

Note in the above example that you would add an author `[a=...]`
attribution if you were merging a branch on behalf of someone else.


-- 
Gustavo Niemeyer
http://niemeyer.net
http://niemeyer.net/blog
http://niemeyer.net/twitter