You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by Marcel Kinard <cm...@gmail.com> on 2013/01/10 16:22:35 UTC
commit messages for newbies
I was contemplating adding the following verbage to the
ContributorWorkflow wiki page. Wanted to float it past the group first
to see if I got it correct.
====
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:
(((
CB-1234: Fixed the whizbang widget
- added more sanity checking in the build script.
- fixed the API to return the correct value in the scenario where there
aren't any whizbangs present.
- corrected the documentation.
)))
Note that the first line does two things:
1) it is less than 40 characters. Subsequent lines after the first may
exceed 40 characters.
2) it references a Jira issue by its id. Commonly, there should be a
Jira issue open for defects and new features, and it is good practice
for commits to point to the Jira issue they are addressing.
Re: commit messages for newbies
Posted by Simon MacDonald <si...@gmail.com>.
+1, maybe we should all follow it :)
Simon Mac Donald
http://hi.im/simonmacdonald
On Fri, Jan 11, 2013 at 1:29 PM, Michael Brooks
<mi...@michaelbrooks.ca> wrote:
> Looks really good, nice work!
>
> On Fri, Jan 11, 2013 at 9:59 AM, Marcel Kinard <cm...@gmail.com> wrote:
>
>> Good points, Michael.
>>
>> Done. Please tweak further where desired. http://wiki.apache.org/**
>> cordova/ContributorWorkflow<http://wiki.apache.org/cordova/ContributorWorkflow>
>>
>> -- Marcel
>>
>>
>> On 1/10/2013 2:23 PM, Michael Brooks wrote:
>>
>>> @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<http://git-scm.com/book/ch5-2.html#Commit-Guidelines>
>>>
>>>
Re: commit messages for newbies
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
Looks really good, nice work!
On Fri, Jan 11, 2013 at 9:59 AM, Marcel Kinard <cm...@gmail.com> wrote:
> Good points, Michael.
>
> Done. Please tweak further where desired. http://wiki.apache.org/**
> cordova/ContributorWorkflow<http://wiki.apache.org/cordova/ContributorWorkflow>
>
> -- Marcel
>
>
> On 1/10/2013 2:23 PM, Michael Brooks wrote:
>
>> @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<http://git-scm.com/book/ch5-2.html#Commit-Guidelines>
>>
>>
Re: commit messages for newbies
Posted by Marcel Kinard <cm...@gmail.com>.
Good points, Michael.
Done. Please tweak further where desired.
http://wiki.apache.org/cordova/ContributorWorkflow
-- Marcel
On 1/10/2013 2:23 PM, Michael Brooks wrote:
> @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
>
Re: commit messages for newbies
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
@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 <js...@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.
>
RE: commit messages for newbies
Posted by Josh Soref <js...@rim.com>.
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.
Re: commit messages for newbies
Posted by Becky Gibson <gi...@gmail.com>.
+1
On Thu, Jan 10, 2013 at 11:48 AM, Giorgio Natili <g....@gnstudio.com>wrote:
> +1
>
> On 1/10/13 4:22 PM, "Marcel Kinard" <cm...@gmail.com> wrote:
>
> >I was contemplating adding the following verbage to the
> >ContributorWorkflow wiki page. Wanted to float it past the group first
> >to see if I got it correct.
> >
> >====
> >
> >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:
> >
> >(((
> >CB-1234: Fixed the whizbang widget
> >- added more sanity checking in the build script.
> >- fixed the API to return the correct value in the scenario where there
> >aren't any whizbangs present.
> >- corrected the documentation.
> >)))
> >
> >Note that the first line does two things:
> >1) it is less than 40 characters. Subsequent lines after the first may
> >exceed 40 characters.
> >2) it references a Jira issue by its id. Commonly, there should be a
> >Jira issue open for defects and new features, and it is good practice
> >for commits to point to the Jira issue they are addressing.
> >
>
>
>
Re: commit messages for newbies
Posted by Giorgio Natili <g....@gnstudio.com>.
+1
On 1/10/13 4:22 PM, "Marcel Kinard" <cm...@gmail.com> wrote:
>I was contemplating adding the following verbage to the
>ContributorWorkflow wiki page. Wanted to float it past the group first
>to see if I got it correct.
>
>====
>
>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:
>
>(((
>CB-1234: Fixed the whizbang widget
>- added more sanity checking in the build script.
>- fixed the API to return the correct value in the scenario where there
>aren't any whizbangs present.
>- corrected the documentation.
>)))
>
>Note that the first line does two things:
>1) it is less than 40 characters. Subsequent lines after the first may
>exceed 40 characters.
>2) it references a Jira issue by its id. Commonly, there should be a
>Jira issue open for defects and new features, and it is good practice
>for commits to point to the Jira issue they are addressing.
>