Commit messages

[Pavel Janík <Pa...@Janik.cz>]

Hi,

I do not know if Apache has some proposed syntax of commit messages (and don't have time to dig around it on the web), but I'd like to see commit log/messages containing the number of fixed issue referenced and no commit messages without that number.

In OOo times, the commit logs were in the following structure:

#12345#: Fix typo (i->y).

Can we do the same/similar in Apache OpenOffice.org?
-- 
Pavel Janík

RE: Commit messages

["Dennis E. Hamilton" <de...@acm.org>]

The capability exists.  There was earlier discussion of what the supported cases are.  

Someone with the details needs to make a request on the INFRA JIRA tracker.

(It could even be working already.  Have to find occasion to fix a bug and see what happens [;<).

 - Dennis

-----Original Message-----
From: Carl Marcum [mailto:carl.marcum@codebuilders.net] 
Sent: Tuesday, August 30, 2011 18:30
To: ooo-dev@incubator.apache.org
Subject: Re: Commit messages

Does anyone know if the bugzilla instance is or can be configured to use 
SVN post-commit hook scripts to update an issue?

I'm familiar with Trac / SVN and it defaults to:
'Refs #123' and 'Fixes #123' to update the issues automatically.

Regards,
Carl

Re: Commit messages

[Carl Marcum <ca...@codebuilders.net>]

Does anyone know if the bugzilla instance is or can be configured to use 
SVN post-commit hook scripts to update an issue?

I'm familiar with Trac / SVN and it defaults to:
'Refs #123' and 'Fixes #123' to update the issues automatically.

Regards,
Carl

Re: Commit messages

["Marcus (OOo)" <ma...@wtnet.de>]

Am 08/28/2011 10:32 PM, schrieb Ross Gardler:
> On Sunday, 28 August 2011, Pavel Janík<Pa...@janik.cz>  wrote:
>> I do not know if Apache has some proposed syntax of commit messages (and
> don't have time to dig around it on the web), but I'd like to see commit
> log/messages containing the number of fixed issue referenced and no commit
> messages without that number.
>>
>> In OOo times, the commit logs were in the following structure:
>>
>> #12345#: Fix typo (i->y).
>>
>> Can we do the same/similar in Apache OpenOffice.org?

As long as we have no - hm, let's say useable - bugtracker it doesn't 
make sense. ;-)

But the migration is already in the run. When it's up and running on 
Apache infra I'm sure we can come back to the old behavior.

Marcus



> OOo can use any syntax it likes, but to help you define it here's my
> observations from other ASF projects.
>
> On projects that use JIRA the syntax is to use the JIRA project ID, e.g.
> "foo-123" (issue 123 on project foo). This will automatically link the issue
> in JIRA to the commit, that is the commit message and links to the duffs
> appear in JIRA comments.
>
> I'm not sure if/how the same effect is achieved using Bugzilla.
>
> It is also recommended that when a commit is a patch from a third party that
> it includes "thanks to Jane Bar". Thus makes it easier to track active
> contributors.
>
> Ross
>
>
>> --
>> Pavel Janík

Re: Commit messages

[Eike Rathke <oo...@erack.de>]

Hi Ross,

On Sunday, 2011-08-28 21:32:52 +0100, Ross Gardler wrote:

> It is also recommended that when a commit is a patch from a third party that
> it includes "thanks to Jane Bar". Thus makes it easier to track active
> contributors.

<nitpick>
Decent DSCMs have distinct author and committer fields.
</nitpick>

;-)

  Eike

-- 
 PGP/OpenPGP/GnuPG encrypted mail preferred in all private communication.
 Key ID: 0x293C05FD - 997A 4C60 CE41 0149 0DB3  9E96 2F1A D073 293C 05FD

Re: Commit messages

[Ross Gardler <rg...@opendirective.com>]

On Sunday, 28 August 2011, Pavel Janík <Pa...@janik.cz> wrote:
> I do not know if Apache has some proposed syntax of commit messages (and
don't have time to dig around it on the web), but I'd like to see commit
log/messages containing the number of fixed issue referenced and no commit
messages without that number.
>
> In OOo times, the commit logs were in the following structure:
>
> #12345#: Fix typo (i->y).
>
> Can we do the same/similar in Apache OpenOffice.org?

OOo can use any syntax it likes, but to help you define it here's my
observations from other ASF projects.

On projects that use JIRA the syntax is to use the JIRA project ID, e.g.
"foo-123" (issue 123 on project foo). This will automatically link the issue
in JIRA to the commit, that is the commit message and links to the duffs
appear in JIRA comments.

I'm not sure if/how the same effect is achieved using Bugzilla.

It is also recommended that when a commit is a patch from a third party that
it includes "thanks to Jane Bar". Thus makes it easier to track active
contributors.

Ross


> --
> Pavel Janík
>
>
>
>

-- 
Ross Gardler (@rgardler)
Programme Leader (Open Development)
OpenDirective http://opendirective.com

Re: Commit messages

["Marcus (OOo)" <ma...@wtnet.de>]

Am 08/30/2011 07:54 PM, schrieb Rob Weir:
> On Tue, Aug 30, 2011 at 1:46 PM, Marcus (OOo)<ma...@wtnet.de>  wrote:
>> Do you remember this one and its usage? ;-)
>>
>> https://issues.apache.org/ooo/show_bug.cgi?id=100000
>>
>> It doesn't make sense to have a issue ID for *every* problem that
>> can/should/has to be fixed in the code. Especially for a build breaker fix
>> in a single line of code a detailed commit message is really sufficient.
>>
>
> Something to keep in mind is that we agree to have different policies
> during different phases of a release cycle.  For example, at the
> beginning of a release we would have a lenient policy:  Commit Then
> Review, no requirement for pre-existing BZ issues, etc.  But then
> after we branch for stabilization, or maybe after beta, or at some
> point where stability is the overriding concern, then we could switch
> to a policy of: Review then Commit, no commits unless accompanied by a
> BZ issue number, etc.
>
> There is a time for "bureaucracy" and we should not hesitate to be
> strict.  But maybe we can narrow this to a small portion of the
> release cycle?

Even in times of Beta and RC the issue ID above was used and the release 
was nevertheless stable.

So, lets see if an ID is always the solution for a problem.

Marcus



>> Am 08/30/2011 06:53 PM, schrieb Michael Stahl:
>>>
>>> On 30.08.2011 17:53, Tor Lillqvist wrote:
>>>>>>
>>>>>> I'd like to see commit log/messages containing the number of fixed
>>>>>> issue referenced and no commit
>>>>>> messages without that number.
>>>>
>>>> So people would not be allowed to improve things without first filing
>>>> issues? Isn't that the kind of bureucracy that gave OOo a bad
>>>> reputation among people who then created LibreOffice?
>>>
>>> i also think that requiring an issue id and thus an issue in the
>>> bugtracker for every commit is overkill.
>>>
>>> there are lots of trivial problems that always pop up (especially
>>> considering that we support many different platforms, and it's not
>>> really possible to test all of them before every commit).
>>>
>>> on the other hand, if there already is an issue for whatever is fixed by
>>> a commit, then that commit should be required to contain the issue id.
>>>
>>>> Also, having an issue number in the commit message is not really that
>>>> helpful, if the commit message is a short one-liner, the bug report
>>>> doesn't describe what the changed/added/fixed code actually does
>>>> either, and no useful comments are added.
>>>
>>> indeed, that sometimes bothered me in the past as well.
>>>
>>> if a bug fix isn't totally obvious, then there should be a comment
>>> somewhere, whether in the code, the commit message, or the issue
>>> referred to by the commit message, as to what went wrong and why this is
>>> the right fix.
>>>
>>>> --tml
>>>
>>> regards,
>>>   michael

Re: Commit messages

[Rob Weir <ro...@robweir.com>]

On Tue, Aug 30, 2011 at 1:46 PM, Marcus (OOo) <ma...@wtnet.de> wrote:
> Do you remember this one and its usage? ;-)
>
> https://issues.apache.org/ooo/show_bug.cgi?id=100000
>
> It doesn't make sense to have a issue ID for *every* problem that
> can/should/has to be fixed in the code. Especially for a build breaker fix
> in a single line of code a detailed commit message is really sufficient.
>

Something to keep in mind is that we agree to have different policies
during different phases of a release cycle.  For example, at the
beginning of a release we would have a lenient policy:  Commit Then
Review, no requirement for pre-existing BZ issues, etc.  But then
after we branch for stabilization, or maybe after beta, or at some
point where stability is the overriding concern, then we could switch
to a policy of: Review then Commit, no commits unless accompanied by a
BZ issue number, etc.

There is a time for "bureaucracy" and we should not hesitate to be
strict.  But maybe we can narrow this to a small portion of the
release cycle?

-Rob

> Marcus
>
>
>
> Am 08/30/2011 06:53 PM, schrieb Michael Stahl:
>>
>> On 30.08.2011 17:53, Tor Lillqvist wrote:
>>>>>
>>>>> I'd like to see commit log/messages containing the number of fixed
>>>>> issue referenced and no commit
>>>>> messages without that number.
>>>
>>> So people would not be allowed to improve things without first filing
>>> issues? Isn't that the kind of bureucracy that gave OOo a bad
>>> reputation among people who then created LibreOffice?
>>
>> i also think that requiring an issue id and thus an issue in the
>> bugtracker for every commit is overkill.
>>
>> there are lots of trivial problems that always pop up (especially
>> considering that we support many different platforms, and it's not
>> really possible to test all of them before every commit).
>>
>> on the other hand, if there already is an issue for whatever is fixed by
>> a commit, then that commit should be required to contain the issue id.
>>
>>> Also, having an issue number in the commit message is not really that
>>> helpful, if the commit message is a short one-liner, the bug report
>>> doesn't describe what the changed/added/fixed code actually does
>>> either, and no useful comments are added.
>>
>> indeed, that sometimes bothered me in the past as well.
>>
>> if a bug fix isn't totally obvious, then there should be a comment
>> somewhere, whether in the code, the commit message, or the issue
>> referred to by the commit message, as to what went wrong and why this is
>> the right fix.
>>
>>> --tml
>>
>> regards,
>>  michael
>

Re: Commit messages

["Marcus (OOo)" <ma...@wtnet.de>]

Do you remember this one and its usage? ;-)

https://issues.apache.org/ooo/show_bug.cgi?id=100000

It doesn't make sense to have a issue ID for *every* problem that 
can/should/has to be fixed in the code. Especially for a build breaker 
fix in a single line of code a detailed commit message is really sufficient.

Marcus



Am 08/30/2011 06:53 PM, schrieb Michael Stahl:
> On 30.08.2011 17:53, Tor Lillqvist wrote:
>>>> I'd like to see commit log/messages containing the number of fixed issue referenced and no commit
>>>> messages without that number.
>>
>> So people would not be allowed to improve things without first filing
>> issues? Isn't that the kind of bureucracy that gave OOo a bad
>> reputation among people who then created LibreOffice?
>
> i also think that requiring an issue id and thus an issue in the
> bugtracker for every commit is overkill.
>
> there are lots of trivial problems that always pop up (especially
> considering that we support many different platforms, and it's not
> really possible to test all of them before every commit).
>
> on the other hand, if there already is an issue for whatever is fixed by
> a commit, then that commit should be required to contain the issue id.
>
>> Also, having an issue number in the commit message is not really that
>> helpful, if the commit message is a short one-liner, the bug report
>> doesn't describe what the changed/added/fixed code actually does
>> either, and no useful comments are added.
>
> indeed, that sometimes bothered me in the past as well.
>
> if a bug fix isn't totally obvious, then there should be a comment
> somewhere, whether in the code, the commit message, or the issue
> referred to by the commit message, as to what went wrong and why this is
> the right fix.
>
>> --tml
>
> regards,
>   michael

Re: Commit messages

[Michael Stahl <ms...@openoffice.org>]

On 30.08.2011 17:53, Tor Lillqvist wrote:
>>> I'd like to see commit log/messages containing the number of fixed issue referenced and no commit
>>> messages without that number.
> 
> So people would not be allowed to improve things without first filing
> issues? Isn't that the kind of bureucracy that gave OOo a bad
> reputation among people who then created LibreOffice?

i also think that requiring an issue id and thus an issue in the
bugtracker for every commit is overkill.

there are lots of trivial problems that always pop up (especially
considering that we support many different platforms, and it's not
really possible to test all of them before every commit).

on the other hand, if there already is an issue for whatever is fixed by
a commit, then that commit should be required to contain the issue id.

> Also, having an issue number in the commit message is not really that
> helpful, if the commit message is a short one-liner, the bug report
> doesn't describe what the changed/added/fixed code actually does
> either, and no useful comments are added.

indeed, that sometimes bothered me in the past as well.

if a bug fix isn't totally obvious, then there should be a comment
somewhere, whether in the code, the commit message, or the issue
referred to by the commit message, as to what went wrong and why this is
the right fix.

> --tml

regards,
 michael

Re: Commit messages

["Pedro F. Giffuni" <gi...@tutopia.com>]

--- On Tue, 8/30/11, Tor Lillqvist <tm...@iki.fi> wrote:
...

>> (I don't know who wrote this ... )
>> I'd like to see commit log/messages containing the
>> number of fixed issue referenced and no commit
>> messages without that number.
> 
> So people would not be allowed to improve things without
> first filing issues? Isn't that the kind of bureucracy

"like to see" doesn't involve any type of imposition.

> 
> Also, having an issue number in the commit message is not
> really that helpful, if the commit message is a short
> one-liner, the bug report doesn't describe what the
> changed/added/fixed code actually does either, and
> no useful comments are added.
>

I think the motivation is that modern bug management tools
integrate very well with the VCS. These are just rules of
thumb though .. committers are responsible for keeping
commit messages useful for community (and their own) benefit.

Pedro.

Re: Commit messages

[Tor Lillqvist <tm...@iki.fi>]

>> I'd like to see commit log/messages containing the number of fixed issue referenced and no commit
>> messages without that number.

So people would not be allowed to improve things without first filing
issues? Isn't that the kind of bureucracy that gave OOo a bad
reputation among people who then created LibreOffice?

Also, having an issue number in the commit message is not really that
helpful, if the commit message is a short one-liner, the bug report
doesn't describe what the changed/added/fixed code actually does
either, and no useful comments are added.

--tml

Re: Commit messages

[Carl Marcum <cm...@apache.org>]

On 08/30/2011 02:09 PM, Greg Stein wrote:
> The Apache Subversion codified and wrote up details on how the project
> should write log messages. This style has been in effect for its
> decade+ duration and has worked out very well. You may find it helpful
> for the (new) OOo log message guidelines:
>
>    http://subversion.apache.org/docs/community-guide/conventions.html#log-messages
>
> Cheers,
> -g
>
> On Tue, Aug 30, 2011 at 10:34, Shane Curcuru<as...@shanecurcuru.org>  wrote:
>> Some projects do this by convention within the committers, using various
>> tags within the log message to denote bug number, reporter, original source,
>> test id, whatever.  But it's up to each project to implement a policy for
>> this at the community level.
>>
>> There's a useful set of commentary on this kind of question here:
>>
>>   https://issues.apache.org/jira/browse/INFRA-3493
>>
>> Note also that SVN allows committers to update log messages after the fact,
>> so you can always add new annotations later if needed.
>>
>> - Shane
>>
>> On 8/28/2011 4:03 PM, Pavel Janík wrote:
>>>
>>> Hi,
>>>
>>> I do not know if Apache has some proposed syntax of commit messages (and
>>> don't have time to dig around it on the web), but I'd like to see commit
>>> log/messages containing the number of fixed issue referenced and no commit
>>> messages without that number.
>>>
>>> In OOo times, the commit logs were in the following structure:
>>>
>>> #12345#: Fix typo (i->y).
>>>
>>> Can we do the same/similar in Apache OpenOffice.org?
>>
>

I like the idea of starting from a something existing like the Apache 
Subversion guidelines and tailoring if needed based on Bugzilla needs etc.

Consistency is good especially for parsing with scripts.

Regards,
Carl

Re: Commit messages

[Greg Stein <gs...@gmail.com>]

The Apache Subversion codified and wrote up details on how the project
should write log messages. This style has been in effect for its
decade+ duration and has worked out very well. You may find it helpful
for the (new) OOo log message guidelines:

  http://subversion.apache.org/docs/community-guide/conventions.html#log-messages

Cheers,
-g

On Tue, Aug 30, 2011 at 10:34, Shane Curcuru <as...@shanecurcuru.org> wrote:
> Some projects do this by convention within the committers, using various
> tags within the log message to denote bug number, reporter, original source,
> test id, whatever.  But it's up to each project to implement a policy for
> this at the community level.
>
> There's a useful set of commentary on this kind of question here:
>
>  https://issues.apache.org/jira/browse/INFRA-3493
>
> Note also that SVN allows committers to update log messages after the fact,
> so you can always add new annotations later if needed.
>
> - Shane
>
> On 8/28/2011 4:03 PM, Pavel Janík wrote:
>>
>> Hi,
>>
>> I do not know if Apache has some proposed syntax of commit messages (and
>> don't have time to dig around it on the web), but I'd like to see commit
>> log/messages containing the number of fixed issue referenced and no commit
>> messages without that number.
>>
>> In OOo times, the commit logs were in the following structure:
>>
>> #12345#: Fix typo (i->y).
>>
>> Can we do the same/similar in Apache OpenOffice.org?
>

Re: Commit messages

[Shane Curcuru <as...@shanecurcuru.org>]

Some projects do this by convention within the committers, using various 
tags within the log message to denote bug number, reporter, original 
source, test id, whatever.  But it's up to each project to implement a 
policy for this at the community level.

There's a useful set of commentary on this kind of question here:

   https://issues.apache.org/jira/browse/INFRA-3493

Note also that SVN allows committers to update log messages after the 
fact, so you can always add new annotations later if needed.

- Shane

On 8/28/2011 4:03 PM, Pavel Janík wrote:
> Hi,
>
> I do not know if Apache has some proposed syntax of commit messages (and don't have time to dig around it on the web), but I'd like to see commit log/messages containing the number of fixed issue referenced and no commit messages without that number.
>
> In OOo times, the commit logs were in the following structure:
>
> #12345#: Fix typo (i->y).
>
> Can we do the same/similar in Apache OpenOffice.org?