Change commit message template?

[Jacques Le Roux]

Hi,

While working in Eclipse with Git (ie using eGit which is not my favourite tool). I found a warning telling me:

    "Second line should be empty to separate commit message header from body"

It was argued that it's only a convention[1], but don't we prefer "convention over configuration"?

I suggest to change our template according to the convention, ie separate the title from the issue number or put the number on the same line (split
sometimes) than the title

[1]https://bugs.eclipse.org/bugs/show_bug.cgi?id=475845

What do you think?

Jacques

[taher]

Hi Jacques,

I'm not sure what convention over configuration has to do with what
you're saying :)

Anyway, it makes sense. Most GIT editors consider the first line to be
subject, and third line onward is the body of the message. So perhaps
we can move the (OFBIZ-XXXX) to the end of the first line or maybe
make it the last line in the body or something like that.


On Sun, Nov 17, 2019 at 7:05 PM Jacques Le Roux
<[hidden email]> wrote:

>
> Hi,
>
> While working in Eclipse with Git (ie using eGit which is not my favourite tool). I found a warning telling me:
>
>     "Second line should be empty to separate commit message header from body"
>
> It was argued that it's only a convention[1], but don't we prefer "convention over configuration"?
>
> I suggest to change our template according to the convention, ie separate the title from the issue number or put the number on the same line (split
> sometimes) than the title
>
> [1]https://bugs.eclipse.org/bugs/show_bug.cgi?id=475845
>
> What do you think?
>
> Jacques
>

[Gil Portenseigne]

Hello,

When we first decided on the current template, i did understood that
jira number was at the end of the first line, that was logical in my
view. I was mistaken and did not discussed it by then.

Setting Jira number at the end of the first line is fine for me.

Gil

Le 21:16 - dimanche 17 nov., Taher Alkhateeb a écrit :

> Hi Jacques,
>
> I'm not sure what convention over configuration has to do with what
> you're saying :)
>
> Anyway, it makes sense. Most GIT editors consider the first line to be
> subject, and third line onward is the body of the message. So perhaps
> we can move the (OFBIZ-XXXX) to the end of the first line or maybe
> make it the last line in the body or something like that.
>
>
> On Sun, Nov 17, 2019 at 7:05 PM Jacques Le Roux
> <[hidden email]> wrote:
> >
> > Hi,
> >
> > While working in Eclipse with Git (ie using eGit which is not my favourite tool). I found a warning telling me:
> >
> >     "Second line should be empty to separate commit message header from body"
> >
> > It was argued that it's only a convention[1], but don't we prefer "convention over configuration"?
> >
> > I suggest to change our template according to the convention, ie separate the title from the issue number or put the number on the same line (split
> > sometimes) than the title
> >
> > [1]https://bugs.eclipse.org/bugs/show_bug.cgi?id=475845
> >
> > What do you think?
> >
> > Jacques
> >

[Jacques Le Roux]

Hi Taher,

Le 17/11/2019 à 19:16, Taher Alkhateeb a écrit :
> Hi Jacques,
>
> I'm not sure what convention over configuration has to do with what
> you're saying :)

It was because of this sentence in the reference link

    "This is a project specific convention that has no relation to any requirements or limitations in Git. Yes, it is a fine convention for many projects but it should not be required."

And yes I abused the concept a bit :) I see our template as a configuration.

> Anyway, it makes sense. Most GIT editors consider the first line to be
> subject, and third line onward is the body of the message. So perhaps
> we can move the (OFBIZ-XXXX) to the end of the first line or maybe
> make it the last line in the body or something like that.

Finally, like Gil, I prefer to keep the 2 infos on the same line. It would make less sense to have the issue number inside the body of the message

Thanks

Jacques

>
>
> On Sun, Nov 17, 2019 at 7:05 PM Jacques Le Roux
> <[hidden email]> wrote:
>> Hi,
>>
>> While working in Eclipse with Git (ie using eGit which is not my favourite tool). I found a warning telling me:
>>
>>      "Second line should be empty to separate commit message header from body"
>>
>> It was argued that it's only a convention[1], but don't we prefer "convention over configuration"?
>>
>> I suggest to change our template according to the convention, ie separate the title from the issue number or put the number on the same line (split
>> sometimes) than the title
>>
>> [1]https://bugs.eclipse.org/bugs/show_bug.cgi?id=475845
>>
>> What do you think?
>>
>> Jacques
>>

[Jacques Le Roux]

Hi Gil,

Yes actually from start that's what I supposed to be the best "solution" too.

In Eclipse I can use that for instance: https://bugs.eclipse.org/bugs/show_bug.cgi?id=471421

Thanks

Jacques

Le 17/11/2019 à 21:08, Gil Portenseigne a écrit :

> Hello,
>
> When we first decided on the current template, i did understood that
> jira number was at the end of the first line, that was logical in my
> view. I was mistaken and did not discussed it by then.
>
> Setting Jira number at the end of the first line is fine for me.
>
> Gil
>
> Le 21:16 - dimanche 17 nov., Taher Alkhateeb a écrit :
>> Hi Jacques,
>>
>> I'm not sure what convention over configuration has to do with what
>> you're saying :)
>>
>> Anyway, it makes sense. Most GIT editors consider the first line to be
>> subject, and third line onward is the body of the message. So perhaps
>> we can move the (OFBIZ-XXXX) to the end of the first line or maybe
>> make it the last line in the body or something like that.
>>
>>
>> On Sun, Nov 17, 2019 at 7:05 PM Jacques Le Roux
>> <[hidden email]> wrote:
>>> Hi,
>>>
>>> While working in Eclipse with Git (ie using eGit which is not my favourite tool). I found a warning telling me:
>>>
>>>      "Second line should be empty to separate commit message header from body"
>>>
>>> It was argued that it's only a convention[1], but don't we prefer "convention over configuration"?
>>>
>>> I suggest to change our template according to the convention, ie separate the title from the issue number or put the number on the same line (split
>>> sometimes) than the title
>>>
>>> [1]https://bugs.eclipse.org/bugs/show_bug.cgi?id=475845
>>>
>>> What do you think?
>>>
>>> Jacques
>>>

[Mathieu Lirzin]

Hello,

Jacques Le Roux <[hidden email]> writes:

> Le 17/11/2019 à 19:16, Taher Alkhateeb a écrit :
>
>> I'm not sure what convention over configuration has to do with what
>> you're saying :)
>
> It was because of this sentence in the reference link
>
>    "This is a project specific convention that has no relation to any requirements or limitations in Git. Yes, it is a fine convention for many projects but it should not be required."
>
> And yes I abused the concept a bit :) I see our template as a configuration.
>
>> Anyway, it makes sense. Most GIT editors consider the first line to be
>> subject, and third line onward is the body of the message. So perhaps
>> we can move the (OFBIZ-XXXX) to the end of the first line or maybe
>> make it the last line in the body or something like that.
>
> Finally, like Gil, I prefer to keep the 2 infos on the same line. It
> would make less sense to have the issue number inside the body of the
> message

IMO to guess what make sense or not, I think considering the usage of
that information matters. For instance a lot of UI ontop of Git show
only the summary (the first line) in a first step to give an overview of
the commit and require a user action to display the details (the body)
of the message commit.

So if we choose to put the ticket number in the summary it is because we
find valuable to see it at first glance otherwise it is just noise.

In other free software communities I work with, the bug ticket number
was only considered as metadata (like our “thanks” part) put in the body
so that it can be easily retrieved with ‘git log --grep=...’
when diving in the history.

I personally don't see any value in having auto generated identifiers
inside the summary of our commits, but if people in this community find
it useful in their workflow, I don't mind following that convention.

--
Mathieu Lirzin

[Samuel-2]

Hi,

agree with Mathieu: I prefer keeping issue id in footer (at the end of
commit message) so we can save some characters in subject line to
express something meaningful.

In addition if we put this information in commit footer (or body) we can
copy the complete link to issue (for example
https://issues.apache.org/jira/browse/OFBIZ-4274 instead of just
OFBIZ-4274) so that we can just "click" on it to display related issue :)

But like Mathieu said, I don't mind if some people find this `OFBIZ-XXX`
so meaningful that they want to keep it on subject line.


Samuel

[Jacques Le Roux]

Hi All, Samuel,

The reason we use only the ref and a not a link to Jira is because so far the commits template is/was(?[1]) used by Michael to deliver the information
you can find a the bottom of our monthly blog entries, eg: https://blogs.apache.org/ofbiz/

I'd like to get ahead. It seems we have a lazy consensus about not putting it in the "title", but in the body

I believe the position of the Jira ref has no influence on this somehow related issue: https://issues.apache.org/jira/browse/INFRA-19471 I created.
But I'll wait to know more about that before changing our template

[1] https://the-asf.slack.com/archives/GFCDJ9FNK (it's the Slack OFBIz-Blog channel, you need to login)

Jacques

Le 18/11/2019 à 10:25, Samuel Trégouët a écrit :

> Hi,
>
> agree with Mathieu: I prefer keeping issue id in footer (at the end of
> commit message) so we can save some characters in subject line to
> express something meaningful.
>
> In addition if we put this information in commit footer (or body) we can
> copy the complete link to issue (for example
> https://issues.apache.org/jira/browse/OFBIZ-4274 instead of just
> OFBIZ-4274) so that we can just "click" on it to display related issue :)
>
> But like Mathieu said, I don't mind if some people find this `OFBIZ-XXX`
> so meaningful that they want to keep it on subject line.
>
>
> Samuel
>