You are viewing a plain text version of this content. The canonical link for it is here.
Posted to zeta-dev@incubator.apache.org by Tobias Schlitt <to...@schlitt.info> on 2011/04/01 14:06:16 UTC
[zeta-dev] Proposal: Commit guidelines
Hi,
I wrote down our commit guidelines. Please review them shortly, before I
commit:
http://files.schlitt.info/tmp/commit_guidelines.patch
Regards,
Toby
--
Tobias Schlitt http://schlitt.info GPG Key: 0xC462BC14
Want to hire me? Need quality assurance? http://qafoo.com
eZ Components are Zeta Components now! http://bit.ly/9S7zbn
Re: [zeta-dev] Proposal: Commit guidelines
Posted by Jerome Renard <je...@gmail.com>.
Hi Tobias,
On Fri, Apr 1, 2011 at 4:06 PM, Tobias Schlitt <to...@schlitt.info> wrote:
> Hi,
>
> I wrote down our commit guidelines. Please review them shortly, before I
> commit:
>
> http://files.schlitt.info/tmp/commit_guidelines.patch
>
Looks good to me.
Cheers :)
--
Jérôme Renard
http://39web.fr | http://jrenard.info | http://twitter.com/jeromerenard
Re: [zeta-dev] Proposal: Commit guidelines
Posted by James Pic <ja...@gmail.com>.
Hi Tobias,
On Fri, Apr 1, 2011 at 4:06 PM, Tobias Schlitt <to...@schlitt.info> wrote:
>
> Hi,
>
> I wrote down our commit guidelines. Please review them shortly, before I
> commit:
>
There is a typo at the end: corrsponding.
Thanks for writing down the commit message guidelines, that'll save
some IRC action.
Cheers
Re: [zeta-dev] Proposal: Commit guidelines
Posted by Tobias Schlitt <to...@schlitt.info>.
On 04/08/2011 11:25 PM, Gav... wrote:
> This whole thread started because the 'actual standards' state to
> only mention the Issue Number in the final commit...
>
> "...+However, larger features or bug fixes, should be split them into
> +smaller commits. In this case, the issue number should only occur
> in +the final commit, which closes the issue..."
>
> As mentioned before, knowing which is really the last commit to close
> an issue is a hard one, and having many commits not tied to an issue
> number makes people wonder what issue it is for.
>
> Jira itself keeps track of commits for a particular issue, but only
> if the commit has the issue number mentioned in the commit message.
>
> See for example:
>
> https://issues.apache.org/jira/browse/ZETACOMP-8?page=com.atlassian.jira.plugin.ext.subversion%3Asubversion-commits-tabpanel#issue-tabs
>
> and most other projects are doing the same thing, i.e.
>
> https://issues.apache.org/jira/browse/FOR-1224?page=com.atlassian.jira.plugin.ext.subversion%3Asubversion-commits-tabpanel#issue-tabs
>
>
> https://issues.apache.org/jira/browse/TS-516?page=com.atlassian.jira.plugin.ext.subversion%3Asubversion-commits-tabpanel#issue-tabs
>
> etc etc...
>
> for that helpful feature alone it is worth the extra few characters
> per commit message.
I agree with Gavin that this would indeed be useful. However, we should
try to not end up with endless infrastructure discussions. :)
What is desired here is a simple way of mentioning the issue number in
each commit where we work on a specific issue.
What about:
- Fixed #ZETACOMP-$x: ...
for the final commit fixing an issue and
- Work #ZETACOMP-$x: ...
for intermediate commits? The "Work" keyword can then be used for both,
issues and enhancements, we don't add much bloat and stick to the
current way of having simple keywords.
Regards,
Toby
--
Tobias Schlitt http://schlitt.info GPG Key: 0xC462BC14
Want to hire me? Need quality assurance? http://qafoo.com
eZ Components are Zeta Components now! http://bit.ly/9S7zbn
RE: [zeta-dev] Proposal: Commit guidelines
Posted by "Gav..." <ga...@16degrees.com.au>.
> -----Original Message-----
> From: James Pic [mailto:jamespic@gmail.com]
> Sent: Saturday, 9 April 2011 2:03 AM
> To: zeta-dev@incubator.apache.org
> Cc: Jerome Renard; Patrick ALLAERT
> Subject: Re: [zeta-dev] Proposal: Commit guidelines
>
<snip>
> That said, I agree that it would be convenient that every commit related to an
> issue would contain the issue number in its message.
This statement contradicts the one below.
>
> Finally, note that Tobias wrote the actual standards that were already used
> and have been proven to work. It is not necessary to bloat them anyway.
This whole thread started because the 'actual standards' state to only mention
the Issue Number in the final commit...
"...+However, larger features or bug fixes, should be split them into
+smaller commits. In this case, the issue number should only occur in
+the final commit, which closes the issue..."
As mentioned before, knowing which is really the last commit to close an issue is
a hard one, and having many commits not tied to an issue number makes people
wonder what issue it is for.
Jira itself keeps track of commits for a particular issue, but only if the commit has the
issue number mentioned in the commit message.
See for example:
https://issues.apache.org/jira/browse/ZETACOMP-8?page=com.atlassian.jira.plugin.ext.subversion%3Asubversion-commits-tabpanel#issue-tabs
and most other projects are doing the same thing, i.e.
https://issues.apache.org/jira/browse/FOR-1224?page=com.atlassian.jira.plugin.ext.subversion%3Asubversion-commits-tabpanel#issue-tabs
https://issues.apache.org/jira/browse/TS-516?page=com.atlassian.jira.plugin.ext.subversion%3Asubversion-commits-tabpanel#issue-tabs
etc etc...
for that helpful feature alone it is worth the extra few characters per commit message.
Gav...
>
> Cheers
>
> James
Re: [zeta-dev] Proposal: Commit guidelines
Posted by James Pic <ja...@gmail.com>.
On Fri, Apr 8, 2011 at 4:29 PM, Jerome Renard <je...@gmail.com> wrote:
>>
>> Normal case is generally to fix issues in one single commit. But it
>> happens that a fix does not fully solve the problem and the bug to be
>> reopened.
>> I think we can simply have something like:
>>
>> First commit solving ZETACOMP-XX:
>> "- Fixed #ZETACOMP-XX: Double conversion of HTML entities"
>>
>> Second commit because of a special case not covered by initial fix:
>> "- Fixed #ZETACOMP-XX: Double conversion of HTML entities
>>
>> Covering the case when ..."
>>
>> This way it is quite easy to look (grep) at "Fixed #ZETACOMP-XX:" for
>> commits related to that issue, knowing that all those commits are
>> required to fully fix the problem.
>>
>
> Well you could use grep on what I proposed as well but this is really a detail.
>
> I like your proposal because it is simpler than mine and also because there is
> a flaw in my proposal : you may never know when you are finished with a fix
> because it can be reopened over and over again, so adding an "END" in a commit
> message does not make any sense.
>
START WIP END is not necessary and is error prone as you demonstrated.
That said, I agree that it would be convenient that every commit
related to an issue would contain the issue number in its message.
Finally, note that Tobias wrote the actual standards that were already
used and have been proven to work. It is not necessary to bloat them
anyway.
Cheers
James
Re: [zeta-dev] Proposal: Commit guidelines
Posted by Jerome Renard <je...@gmail.com>.
Hello Patrick :)
On Fri, Apr 8, 2011 at 4:06 PM, Patrick ALLAERT <pa...@php.net> wrote:
> 2011/4/8 Jerome Renard <je...@gmail.com>:
[...]
>>>
>>> Perhaps it's possible to come up with some other (fixed) term instead of "part
>>> X" after the issue number. A term that means something like: "not
>>> finished", "to be continued" or whatever. It shouldn't be to long. Perhaps an
>>> abbreviation.
>>>
>>
>> Why not, how about something like this ?
>>
>> - Fixed #XXX : bla bla bla START
>> - Fixed #XXX : bla bla bla WIP
>> [...]
>> - Fixed #XXX : bla bla bla END
>
> Should we really mention all that info?
>
Yes because it is part of the convention, well the "Fixed #XXX : bla
bla bla" part.
> I would propose to only use:
> - Fixed #XXX: ...
>
> Normal case is generally to fix issues in one single commit. But it
> happens that a fix does not fully solve the problem and the bug to be
> reopened.
> I think we can simply have something like:
>
> First commit solving ZETACOMP-XX:
> "- Fixed #ZETACOMP-XX: Double conversion of HTML entities"
>
> Second commit because of a special case not covered by initial fix:
> "- Fixed #ZETACOMP-XX: Double conversion of HTML entities
>
> Covering the case when ..."
>
> This way it is quite easy to look (grep) at "Fixed #ZETACOMP-XX:" for
> commits related to that issue, knowing that all those commits are
> required to fully fix the problem.
>
Well you could use grep on what I proposed as well but this is really a detail.
I like your proposal because it is simpler than mine and also because there is
a flaw in my proposal : you may never know when you are finished with a fix
because it can be reopened over and over again, so adding an "END" in a commit
message does not make any sense.
--
Jérôme Renard
http://39web.fr | http://jrenard.info | http://twitter.com/jeromerenard
Re: [zeta-dev] Proposal: Commit guidelines
Posted by Patrick ALLAERT <pa...@php.net>.
2011/4/8 Jerome Renard <je...@gmail.com>:
> Hi Thomas,
>
> On Fri, Apr 8, 2011 at 11:09 AM, Thomas Nunninger <th...@nunninger.info> wrote:
>> Hi,
>>
>> Am Freitag, 8. April 2011 07:50:20 schrieb Jerome Renard:
>>> Hi Patrick,
>>>
>>> On Thu, Apr 7, 2011 at 4:09 PM, Patrick ALLAERT
>>>
>>> <pa...@gmail.com> wrote:
>>> > 2011/4/1 Tobias Schlitt <to...@schlitt.info>:
>>> >> Hi,
>>> >>
>>> >> I wrote down our commit guidelines. Please review them shortly, before I
>>> >> commit:
>>> >>
>>> >> http://files.schlitt.info/tmp/commit_guidelines.patch
>>> >
>>> > Good work Toby!
>>> >
>>> > I have however a remark regarding:
>>> >
>>> > +However, larger features or bug fixes, should be split them into smaller
>>> > +commits. In this case, the issue number should only occur in the final
>>> > commit, +which closes the issue.
>>> >
>>> > I think having the issue number on the latest commit only might be a
>>> > problem for different reasons:
>>> > 1. While looking at a commit mentioning an issue ID, you have no clue
>>> > whether other commits are required or not to fix that specific issue.
>>> > 2. In the case a commit fixing a bug has to be reverted for whatever
>>> > the reason, the one which will definitely resolve the problem will
>>> > also mention that issue which is not consistent to the guidelines.
>>> > 3. In the case a bug issue is reopened, we might have the same problem as
>>> > in 2.
>>>
>>> I already thought about this problem but to be honnest I never found
>>> an acceptable
>>> solution. The only "solution" I came up with is to write commit log
>>> message like this:
>>>
>>> - Fixed #1234321 part 1 : bla bla bla bla
>>
>> Perhaps it's possible to come up with some other (fixed) term instead of "part
>> X" after the issue number. A term that means something like: "not
>> finished", "to be continued" or whatever. It shouldn't be to long. Perhaps an
>> abbreviation.
>>
>
> Why not, how about something like this ?
>
> - Fixed #XXX : bla bla bla START
> - Fixed #XXX : bla bla bla WIP
> [...]
> - Fixed #XXX : bla bla bla END
Should we really mention all that info?
I would propose to only use:
- Fixed #XXX: ...
Normal case is generally to fix issues in one single commit. But it
happens that a fix does not fully solve the problem and the bug to be
reopened.
I think we can simply have something like:
First commit solving ZETACOMP-XX:
"- Fixed #ZETACOMP-XX: Double conversion of HTML entities"
Second commit because of a special case not covered by initial fix:
"- Fixed #ZETACOMP-XX: Double conversion of HTML entities
Covering the case when ..."
This way it is quite easy to look (grep) at "Fixed #ZETACOMP-XX:" for
commits related to that issue, knowing that all those commits are
required to fully fix the problem.
Cheers,
Patrick
--
Patrick Allaert
---
http://code.google.com/p/peclapm/ - Alternative PHP Monitor
Re: [zeta-dev] Proposal: Commit guidelines
Posted by Jerome Renard <je...@gmail.com>.
Hi Thomas,
On Fri, Apr 8, 2011 at 11:09 AM, Thomas Nunninger <th...@nunninger.info> wrote:
> Hi,
>
> Am Freitag, 8. April 2011 07:50:20 schrieb Jerome Renard:
>> Hi Patrick,
>>
>> On Thu, Apr 7, 2011 at 4:09 PM, Patrick ALLAERT
>>
>> <pa...@gmail.com> wrote:
>> > 2011/4/1 Tobias Schlitt <to...@schlitt.info>:
>> >> Hi,
>> >>
>> >> I wrote down our commit guidelines. Please review them shortly, before I
>> >> commit:
>> >>
>> >> http://files.schlitt.info/tmp/commit_guidelines.patch
>> >
>> > Good work Toby!
>> >
>> > I have however a remark regarding:
>> >
>> > +However, larger features or bug fixes, should be split them into smaller
>> > +commits. In this case, the issue number should only occur in the final
>> > commit, +which closes the issue.
>> >
>> > I think having the issue number on the latest commit only might be a
>> > problem for different reasons:
>> > 1. While looking at a commit mentioning an issue ID, you have no clue
>> > whether other commits are required or not to fix that specific issue.
>> > 2. In the case a commit fixing a bug has to be reverted for whatever
>> > the reason, the one which will definitely resolve the problem will
>> > also mention that issue which is not consistent to the guidelines.
>> > 3. In the case a bug issue is reopened, we might have the same problem as
>> > in 2.
>>
>> I already thought about this problem but to be honnest I never found
>> an acceptable
>> solution. The only "solution" I came up with is to write commit log
>> message like this:
>>
>> - Fixed #1234321 part 1 : bla bla bla bla
>
> Perhaps it's possible to come up with some other (fixed) term instead of "part
> X" after the issue number. A term that means something like: "not
> finished", "to be continued" or whatever. It shouldn't be to long. Perhaps an
> abbreviation.
>
Why not, how about something like this ?
- Fixed #XXX : bla bla bla START
- Fixed #XXX : bla bla bla WIP
[...]
- Fixed #XXX : bla bla bla END
--
Jérôme Renard
http://39web.fr | http://jrenard.info | http://twitter.com/jeromerenard
Re: [zeta-dev] Proposal: Commit guidelines
Posted by Thomas Nunninger <th...@nunninger.info>.
Hi,
Am Freitag, 8. April 2011 07:50:20 schrieb Jerome Renard:
> Hi Patrick,
>
> On Thu, Apr 7, 2011 at 4:09 PM, Patrick ALLAERT
>
> <pa...@gmail.com> wrote:
> > 2011/4/1 Tobias Schlitt <to...@schlitt.info>:
> >> Hi,
> >>
> >> I wrote down our commit guidelines. Please review them shortly, before I
> >> commit:
> >>
> >> http://files.schlitt.info/tmp/commit_guidelines.patch
> >
> > Good work Toby!
> >
> > I have however a remark regarding:
> >
> > +However, larger features or bug fixes, should be split them into smaller
> > +commits. In this case, the issue number should only occur in the final
> > commit, +which closes the issue.
> >
> > I think having the issue number on the latest commit only might be a
> > problem for different reasons:
> > 1. While looking at a commit mentioning an issue ID, you have no clue
> > whether other commits are required or not to fix that specific issue.
> > 2. In the case a commit fixing a bug has to be reverted for whatever
> > the reason, the one which will definitely resolve the problem will
> > also mention that issue which is not consistent to the guidelines.
> > 3. In the case a bug issue is reopened, we might have the same problem as
> > in 2.
>
> I already thought about this problem but to be honnest I never found
> an acceptable
> solution. The only "solution" I came up with is to write commit log
> message like this:
>
> - Fixed #1234321 part 1 : bla bla bla bla
Perhaps it's possible to come up with some other (fixed) term instead of "part
X" after the issue number. A term that means something like: "not
finished", "to be continued" or whatever. It shouldn't be to long. Perhaps an
abbreviation.
Regards,
Thomas
>
> That way you actually now which commits are related to which issue but
> I really do not
> like this solution at all. The ideal solution would be to create a new
> branch named "issue-XXX"
> which contain as many commits as required and then push/merge the
> branch when the
> issue/feature is fixed/implemented. But that requires Git (or
> Mercurial) and ASF only provides
> SVN (Git is only a read only mirror).
>
> :)
--
Dipl.-Inf. Thomas Nunninger
Steinhalde 108
79117 Freiburg
Tel.: +49 761 1201850
Mobil: +49 163 7115153
http://nunninger.info
USt-IdNr: DE259832548
Re: [zeta-dev] Proposal: Commit guidelines
Posted by Jerome Renard <je...@gmail.com>.
Hi Patrick,
On Thu, Apr 7, 2011 at 4:09 PM, Patrick ALLAERT
<pa...@gmail.com> wrote:
> 2011/4/1 Tobias Schlitt <to...@schlitt.info>:
>> Hi,
>>
>> I wrote down our commit guidelines. Please review them shortly, before I
>> commit:
>>
>> http://files.schlitt.info/tmp/commit_guidelines.patch
>
> Good work Toby!
>
> I have however a remark regarding:
>
> +However, larger features or bug fixes, should be split them into smaller
> +commits. In this case, the issue number should only occur in the final commit,
> +which closes the issue.
>
> I think having the issue number on the latest commit only might be a
> problem for different reasons:
> 1. While looking at a commit mentioning an issue ID, you have no clue
> whether other commits are required or not to fix that specific issue.
> 2. In the case a commit fixing a bug has to be reverted for whatever
> the reason, the one which will definitely resolve the problem will
> also mention that issue which is not consistent to the guidelines.
> 3. In the case a bug issue is reopened, we might have the same problem as in 2.
>
I already thought about this problem but to be honnest I never found
an acceptable
solution. The only "solution" I came up with is to write commit log
message like this:
- Fixed #1234321 part 1 : bla bla bla bla
That way you actually now which commits are related to which issue but
I really do not
like this solution at all. The ideal solution would be to create a new
branch named "issue-XXX"
which contain as many commits as required and then push/merge the
branch when the
issue/feature is fixed/implemented. But that requires Git (or
Mercurial) and ASF only provides
SVN (Git is only a read only mirror).
:)
--
Jérôme Renard
http://39web.fr | http://jrenard.info | http://twitter.com/jeromerenard
Re: [zeta-dev] Proposal: Commit guidelines
Posted by Patrick ALLAERT <pa...@gmail.com>.
2011/4/1 Tobias Schlitt <to...@schlitt.info>:
> Hi,
>
> I wrote down our commit guidelines. Please review them shortly, before I
> commit:
>
> http://files.schlitt.info/tmp/commit_guidelines.patch
Good work Toby!
I have however a remark regarding:
+However, larger features or bug fixes, should be split them into smaller
+commits. In this case, the issue number should only occur in the final commit,
+which closes the issue.
I think having the issue number on the latest commit only might be a
problem for different reasons:
1. While looking at a commit mentioning an issue ID, you have no clue
whether other commits are required or not to fix that specific issue.
2. In the case a commit fixing a bug has to be reverted for whatever
the reason, the one which will definitely resolve the problem will
also mention that issue which is not consistent to the guidelines.
3. In the case a bug issue is reopened, we might have the same problem as in 2.
Those issue are mostly annoying for bugs.
Is there a drawback that every commits related to an issue is using
the same format as for the final one?
Using it systematically for bugs and not for feature request is a
possible workaround, but it introduces a difference in the process of
handling issues depending on the type we might want to avoid.
Cheers,
Patrick