[PROPOSAL] Guidelines for commit messages

[Richard Downer <ri...@apache.org>]

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

Re: [PROPOSAL] Guidelines for commit messages

[Richard Downer <ri...@apache.org>]

Thanks all for your comments. It seems that the consensus is that
Tim's git article is a good practice, and that our developer guides
should push contributors in that direction, but that it is should not
be any stronger than that.

I'll propose a change to our developer guides.

Richard.


On 2 February 2015 at 14:05, Duncan Grant
<du...@cloudsoftcorp.com> wrote:
> I use fugitive, tim Pope's git plugin for vim.  Turns out I've been trained
> to do this through the power of syntax highlighting.
>
> Anyway...
>
> I think this is a good idea for the reasons listed in the article and would
> favour at least applying it internally and encouraging it externally.
>
> I don't think it would be a barrier to new contributors. Most developers
> expect lots of feedback on their initial PRs so while you shouldn't write
> "your subject is too long please reduce to 50chars" you could write "We try
> to keep our subject lines to 50 chars - consider rewriting as 'Shorter
> message'". And let's face it we should always aim for constructive commit
> feedback.
>
> Duncan
>
>
>
> On 2 February 2015 at 12:25, Martin Harris <ma...@cloudsoftcorp.com>
> wrote:
>
>> This all seems to make sense. I tend to (lazily) use `git commit -am "foo
>> bar baz"` for commit messages, so I'll need to change my workflow but it
>> sounds like a good thing
>>
>> One concern is that this could become a barrier to new contributors. If I
>> was brand new to Brooklyn, and was told that my first PR wasn't going to be
>> merged because my commit message was 80 characters long, I'd be a bit
>> miffed! How about we apply the rule more strictly for seasoned contributors
>> and a little (or lot) more leniently for new contributors - maybe merge
>> their PR with a link to the relevant docs "For their next PR"
>>
>> Cheers
>>
>> M
>>
>> On 2 February 2015 at 12:12, Aled Sage <al...@gmail.com> wrote:
>>
>> > I agree with Tim Pope's guidelines - describing it as best practice
>> rather
>> > than a hard rule is fine with me.
>> >
>> > Note that Tim's blog says that the 50 char summary "isn’t a hard
>> maximum".
>> > We should aim for 50 chars in most cases, but not worry if it goes a bit
>> > above.
>> >
>> > I like the idea of a "git tips and tricks" page (possibly renamed to "git
>> > recommendations, tips and tricks"?). The developer page can link to that.
>> >
>> > Aled
>> >
>> > p.s. I've been meaning for quite some time to incorporate the suggestions
>> > from [1] into the brooklyn docs as well.
>> >
>> > [1] https://groups.google.com/forum/#!msg/jclouds-dev/
>> > iZYY5TyrgA0/QQjS9t4CUM8J
>> >
>> >
>> >
>> > On 02/02/2015 11:13, Alex Heneveld wrote:
>> >
>> >>
>> >> Personally I'm unconvinced the value of this "best practice".  The short
>> >> summary line looks nice but sometimes it is just too short to give a
>> decent
>> >> description. I think I prefer a sufficiently detailed description in the
>> >> summary line.  Slightly longer lines have never bothered me, if
>> justified.
>> >> I was sometimes writing very long first lines, which Richard (and the
>> >> article) convinced me *is* silly.  However I still prefer to suggest
>> best
>> >> practice to people on an ad hoc basis, not something formal. I'd be
>> happy
>> >> with a "Git tips and tricks" section containing this but I'm (weakly)
>> >> against anything more official.
>> >>
>> >> --A
>> >>
>> >>
>> >> On 02/02/2015 10:24, Richard Downer wrote:
>> >>
>> >>> 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
>> >>>
>> >>
>> >>
>> >
>>
>>
>> --
>> Martin Harris
>> Lead Software Engineer
>> Cloudsoft Corporation Ltd
>> www.cloudsoftcorp.com
>> Mobile: +44 (0)7989 047-855
>>

Re: [PROPOSAL] Guidelines for commit messages

[Duncan Grant <du...@cloudsoftcorp.com>]

I use fugitive, tim Pope's git plugin for vim.  Turns out I've been trained
to do this through the power of syntax highlighting.

Anyway...

I think this is a good idea for the reasons listed in the article and would
favour at least applying it internally and encouraging it externally.

I don't think it would be a barrier to new contributors. Most developers
expect lots of feedback on their initial PRs so while you shouldn't write
"your subject is too long please reduce to 50chars" you could write "We try
to keep our subject lines to 50 chars - consider rewriting as 'Shorter
message'". And let's face it we should always aim for constructive commit
feedback.

Duncan



On 2 February 2015 at 12:25, Martin Harris <ma...@cloudsoftcorp.com>
wrote:

> This all seems to make sense. I tend to (lazily) use `git commit -am "foo
> bar baz"` for commit messages, so I'll need to change my workflow but it
> sounds like a good thing
>
> One concern is that this could become a barrier to new contributors. If I
> was brand new to Brooklyn, and was told that my first PR wasn't going to be
> merged because my commit message was 80 characters long, I'd be a bit
> miffed! How about we apply the rule more strictly for seasoned contributors
> and a little (or lot) more leniently for new contributors - maybe merge
> their PR with a link to the relevant docs "For their next PR"
>
> Cheers
>
> M
>
> On 2 February 2015 at 12:12, Aled Sage <al...@gmail.com> wrote:
>
> > I agree with Tim Pope's guidelines - describing it as best practice
> rather
> > than a hard rule is fine with me.
> >
> > Note that Tim's blog says that the 50 char summary "isn’t a hard
> maximum".
> > We should aim for 50 chars in most cases, but not worry if it goes a bit
> > above.
> >
> > I like the idea of a "git tips and tricks" page (possibly renamed to "git
> > recommendations, tips and tricks"?). The developer page can link to that.
> >
> > Aled
> >
> > p.s. I've been meaning for quite some time to incorporate the suggestions
> > from [1] into the brooklyn docs as well.
> >
> > [1] https://groups.google.com/forum/#!msg/jclouds-dev/
> > iZYY5TyrgA0/QQjS9t4CUM8J
> >
> >
> >
> > On 02/02/2015 11:13, Alex Heneveld wrote:
> >
> >>
> >> Personally I'm unconvinced the value of this "best practice".  The short
> >> summary line looks nice but sometimes it is just too short to give a
> decent
> >> description. I think I prefer a sufficiently detailed description in the
> >> summary line.  Slightly longer lines have never bothered me, if
> justified.
> >> I was sometimes writing very long first lines, which Richard (and the
> >> article) convinced me *is* silly.  However I still prefer to suggest
> best
> >> practice to people on an ad hoc basis, not something formal. I'd be
> happy
> >> with a "Git tips and tricks" section containing this but I'm (weakly)
> >> against anything more official.
> >>
> >> --A
> >>
> >>
> >> On 02/02/2015 10:24, Richard Downer wrote:
> >>
> >>> 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
> >>>
> >>
> >>
> >
>
>
> --
> Martin Harris
> Lead Software Engineer
> Cloudsoft Corporation Ltd
> www.cloudsoftcorp.com
> Mobile: +44 (0)7989 047-855
>

Re: [PROPOSAL] Guidelines for commit messages

[Martin Harris <ma...@cloudsoftcorp.com>]

This all seems to make sense. I tend to (lazily) use `git commit -am "foo
bar baz"` for commit messages, so I'll need to change my workflow but it
sounds like a good thing

One concern is that this could become a barrier to new contributors. If I
was brand new to Brooklyn, and was told that my first PR wasn't going to be
merged because my commit message was 80 characters long, I'd be a bit
miffed! How about we apply the rule more strictly for seasoned contributors
and a little (or lot) more leniently for new contributors - maybe merge
their PR with a link to the relevant docs "For their next PR"

Cheers

M

On 2 February 2015 at 12:12, Aled Sage <al...@gmail.com> wrote:

> I agree with Tim Pope's guidelines - describing it as best practice rather
> than a hard rule is fine with me.
>
> Note that Tim's blog says that the 50 char summary "isn’t a hard maximum".
> We should aim for 50 chars in most cases, but not worry if it goes a bit
> above.
>
> I like the idea of a "git tips and tricks" page (possibly renamed to "git
> recommendations, tips and tricks"?). The developer page can link to that.
>
> Aled
>
> p.s. I've been meaning for quite some time to incorporate the suggestions
> from [1] into the brooklyn docs as well.
>
> [1] https://groups.google.com/forum/#!msg/jclouds-dev/
> iZYY5TyrgA0/QQjS9t4CUM8J
>
>
>
> On 02/02/2015 11:13, Alex Heneveld wrote:
>
>>
>> Personally I'm unconvinced the value of this "best practice".  The short
>> summary line looks nice but sometimes it is just too short to give a decent
>> description. I think I prefer a sufficiently detailed description in the
>> summary line.  Slightly longer lines have never bothered me, if justified.
>> I was sometimes writing very long first lines, which Richard (and the
>> article) convinced me *is* silly.  However I still prefer to suggest best
>> practice to people on an ad hoc basis, not something formal. I'd be happy
>> with a "Git tips and tricks" section containing this but I'm (weakly)
>> against anything more official.
>>
>> --A
>>
>>
>> On 02/02/2015 10:24, Richard Downer wrote:
>>
>>> 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
>>>
>>
>>
>


-- 
Martin Harris
Lead Software Engineer
Cloudsoft Corporation Ltd
www.cloudsoftcorp.com
Mobile: +44 (0)7989 047-855

Re: [PROPOSAL] Guidelines for commit messages

[Aled Sage <al...@gmail.com>]

I agree with Tim Pope's guidelines - describing it as best practice 
rather than a hard rule is fine with me.

Note that Tim's blog says that the 50 char summary "isn’t a hard 
maximum". We should aim for 50 chars in most cases, but not worry if it 
goes a bit above.

I like the idea of a "git tips and tricks" page (possibly renamed to 
"git recommendations, tips and tricks"?). The developer page can link to 
that.

Aled

p.s. I've been meaning for quite some time to incorporate the 
suggestions from [1] into the brooklyn docs as well.

[1] 
https://groups.google.com/forum/#!msg/jclouds-dev/iZYY5TyrgA0/QQjS9t4CUM8J


On 02/02/2015 11:13, Alex Heneveld wrote:
>
> Personally I'm unconvinced the value of this "best practice".  The 
> short summary line looks nice but sometimes it is just too short to 
> give a decent description. I think I prefer a sufficiently detailed 
> description in the summary line.  Slightly longer lines have never 
> bothered me, if justified.  I was sometimes writing very long first 
> lines, which Richard (and the article) convinced me *is* silly.  
> However I still prefer to suggest best practice to people on an ad hoc 
> basis, not something formal. I'd be happy with a "Git tips and tricks" 
> section containing this but I'm (weakly) against anything more official.
>
> --A
>
>
> On 02/02/2015 10:24, Richard Downer wrote:
>> 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
>

Re: [PROPOSAL] Guidelines for commit messages

[Alex Heneveld <al...@cloudsoftcorp.com>]

Personally I'm unconvinced the value of this "best practice".  The short 
summary line looks nice but sometimes it is just too short to give a 
decent description. I think I prefer a sufficiently detailed description 
in the summary line.  Slightly longer lines have never bothered me, if 
justified.  I was sometimes writing very long first lines, which Richard 
(and the article) convinced me *is* silly.  However I still prefer to 
suggest best practice to people on an ad hoc basis, not something 
formal. I'd be happy with a "Git tips and tricks" section containing 
this but I'm (weakly) against anything more official.

--A


On 02/02/2015 10:24, Richard Downer wrote:
> 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