Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (athena.apache.org: domain of mikeywbrooks@gmail.com
 designates 209.85.214.178 as permitted sender)
MIME-Version: 1.0
Sender: mikeywbrooks@gmail.com
In-Reply-To: <957F1ECDA90E004B8DBDE23CFC94E3A33A5D3CC5@XMB103ECNC.rim.net>
References: <50EEDCBB.4020305@gmail.com>
	<957F1ECDA90E004B8DBDE23CFC94E3A33A5D3CC5@XMB103ECNC.rim.net>
Date: Thu, 10 Jan 2013 11:23:12 -0800
Message-ID: 
 <CAP7NMPrUDZQS1=eNz93odnS9svsK6Ni4Lcqa9ZYV2EnDB92Hzg@mail.gmail.com>
Subject: Re: commit messages for newbies
From: Michael Brooks <michael@michaelbrooks.ca>
To: dev@cordova.apache.org
Content-Type: multipart/alternative; boundary=e89a8f92407828eb8604d2f41c51

--e89a8f92407828eb8604d2f41c51
Content-Type: text/plain; charset=ISO-8859-1

@Marcel nice work, I agree we should add this to the wiki article.

One note is that I believe you should have an empty line between the
summary and detailed body.

The Pro Git Books [1] summaries the git messages templates as:

Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded by a
   single space, with blank lines in between, but conventions vary here


@Josh

I think short commit messages and multiple tiny commits are fine (and
good). For me, the most important part of the commit message is a reference
to the issue that it is related to. For example, "[CB-1287] Rename such and
such." The issue reference groups all of the tiny commits into a common
task.

[1] http://git-scm.com/book/ch5-2.html#Commit-Guidelines

On Thu, Jan 10, 2013 at 9:11 AM, Josh Soref <jsoref@rim.com> wrote:

> Marcel wrote:
> > A note about commit messages: you are highly encouraged to describe your
> > commit with enough detail for someone else to understand it. In doing
> > so, your commit message can consist of multiple lines. However, it also
> > is highly encouraged that the first line of your commit message not
> > exceed 40 characters. This is because some of the tooling that sits on
> > top of git (such as the httpd apps that let you browse the repo) assume
> > that the first line is top-level summary that is 40 characters or less.
> > Thus there will be highlighting and truncating of the commit message
> > using these assumptions, and it will look weird if these assumptions are
> > not kept. For example, here is a good example of a commit message:
>
> What should a contributor do if they're sending a bunch of changes which
> they'd like someone else to fold/resummarize as the merger wishes?
>
> Note that I'm talking about sending dozens of tiny commits (I've probably
> sent hundreds at this point to Cordova in fact). While I appreciate (and
> really want) good commit messages for certain classes of things, if you
> make the overhead for me too high, I can assure you that there are other
> projects to which I can allocate my spare time instead.
>
> ---------------------------------------------------------------------
> This transmission (including any attachments) may contain confidential
> information, privileged material (including material protected by the
> solicitor-client or other applicable privileges), or constitute non-public
> information. Any use of this information by anyone other than the intended
> recipient is prohibited. If you have received this transmission in error,
> please immediately reply to the sender and delete this information from
> your system. Use, dissemination, distribution, or reproduction of this
> transmission by unintended recipients is not authorized and may be unlawful.
>

--e89a8f92407828eb8604d2f41c51--