Mailing-List: contact dev-help@brooklyn.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@brooklyn.incubator.apache.org
MIME-Version: 1.0
Date: Mon, 2 Feb 2015 10:24:36 +0000
Message-ID: 
 <CABQFKi1xYHn5Ue_L8esXF_OK5U9xFro8T-Q02=FrV4hM8bkGtQ@mail.gmail.com>
Subject: [PROPOSAL] Guidelines for commit messages
From: Richard Downer <richard@apache.org>
To: Brooklyn dev <dev@brooklyn.incubator.apache.org>
Content-Type: text/plain; charset=UTF-8

A recent discussion in a PR[1] covered commit messages. During this
discussion it was discovered that at least two of the committers
follow Tim Pope's guidelines for Git commit messages[2] and recommend
them.

I recommend you read the article, but the short form is that commit
messages look like this:
- Line 1 is a short summary of up to approx 50 characters
- Line 2 is blank
- Lines 3 onwards are a longer description of the change, word-wrapped
at 72 characters

Tim's article lists several advantages relating to the Git command
line tool, but it is also true that GitHub assumes some of these
conventions; in particular, using more text in line 1 wraps in an ugly
way when viewed on GitHub.

I would like to propose that we adopt these as the preferred style for
Brooklyn commits, and that a page is added to the "developers" section
of the website with a precis of, and link to Tim's article.

Any comments for or against this? Any other things we should consider
for commit messages?

Richard.


[1]https://github.com/apache/incubator-brooklyn/pull/481
[2]http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html