You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@couchdb.apache.org by Robert Newson <rn...@apache.org> on 2013/05/27 17:42:34 UTC
[VOTE] Git Commit Messages
Hi All,
Rather than manually maintaining the NEWS and CHANGES files I'd like
to save us time by using the output of git log as our release notes
after 1.3.1.
To make this work we'll need to be better at commit messages. The de
facto standard for git commit messages is described at
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
and I would like us all to commit to using these guidelines, with some
clarifications:
1) The last line of the commit should mention the JIRA ticket.
2) The first line does *not* end with punctuation.
Here's a good, albeit sarcastic, example;
--
Report name of rejected attachment
Some users make requests from inside a black box with a blindfold on
and their eyes closed and are thus sometimes unaware of the names of
their own attachments. Let's help these people.
BugzID: 17669
--
The first line of each log between releases will form the release notes.
I'd like to vote on two questions;
1) That we adopt the git commit message guidelines above.
2) That we delete NEWS/CHANGES from master before the next release after 1.3.1.
The voting rules are lazy consensus with a 72 hour waiting period. You
do not have to vote if you agree, though you are welcome to do so. If
you do vote against I encourage you to include a constructive reason
or suggest an alternative.
B.
Re: [VOTE] Git Commit Messages
Posted by Adam Kocoloski <ko...@apache.org>.
On May 27, 2013, at 11:42 AM, Robert Newson <rn...@apache.org> wrote:
> 1) That we adopt the git commit message guidelines above.
+1. Consistent, well-written, thorough commit messages are one of the better gifts we can give to future developers of CouchDB.
> 2) That we delete NEWS/CHANGES from master before the next release after 1.3.1.
Abstaining here. I'm sure there's a better way to generate release notes than what we do today. I don't feel confident to say whether we have an alternative in place in time for 1.3.1.
Adam
Re: [VOTE] Git Commit Messages
Posted by Klaus Trainer <kl...@posteo.de>.
I'm voting +1 on both questions.
On Mon, 2013-05-27 at 16:42 +0100, Robert Newson wrote:
> Hi All,
>
> Rather than manually maintaining the NEWS and CHANGES files I'd like
> to save us time by using the output of git log as our release notes
> after 1.3.1.
>
> To make this work we'll need to be better at commit messages. The de
> facto standard for git commit messages is described at
> http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
> and I would like us all to commit to using these guidelines, with some
> clarifications:
>
> 1) The last line of the commit should mention the JIRA ticket.
> 2) The first line does *not* end with punctuation.
>
> Here's a good, albeit sarcastic, example;
>
> --
> Report name of rejected attachment
>
> Some users make requests from inside a black box with a blindfold on
> and their eyes closed and are thus sometimes unaware of the names of
> their own attachments. Let's help these people.
>
> BugzID: 17669
> --
>
> The first line of each log between releases will form the release notes.
>
> I'd like to vote on two questions;
>
> 1) That we adopt the git commit message guidelines above.
> 2) That we delete NEWS/CHANGES from master before the next release after 1.3.1.
>
> The voting rules are lazy consensus with a 72 hour waiting period. You
> do not have to vote if you agree, though you are welcome to do so. If
> you do vote against I encourage you to include a constructive reason
> or suggest an alternative.
>
>
> B.
Re: [VOTE] Git Commit Messages
Posted by Russell Branca <ch...@apache.org>.
I'm a big +1 to proposal 1) for better and more structured commit messages.
I'm -1 to the addition of adding the JIRA ticket in the message itself, as
that should be 50 characters or less, and you can have the ticket id in the
full message body and also in the original topic branch name.
As for proposal 2), I think that anything we can do to simplify creation of
releases is a good direction to go in. I do wonder if generating a release
from the commit log requires us to change our approach to commits in the
master branch. Should every commit that lands in master be a single commit
that is a fully squashed topic branch corresponding to a JIRA ticket? It
seems potentially problematic to require a direct mapping between every
commit and release note line items. Overall I like the idea of automating
release notes as much as possible.
-Russell
On Tue, May 28, 2013 at 12:44 PM, Robert Newson <rn...@apache.org> wrote:
> Benoit,
>
> Yes, agreed. I think this joins up with Adam's point too. We need to
> take more care with commit messages in general, and how features/fixes
> are represented in git. We have a thread on the latter already but, to
> address your points, we can include this style of commit on the merge
> commit for those features/fixes that are better represented as
> multiple commits.
>
> I concede the point that we can't ditch NEWS and CHANGES soon, so I'll
> retract that question. For 1.4, I suggest we try to base our release
> notes from the git log, with whatever modifications we end up making,
> and only then decide what our new process looks like.
>
> B.
>
>
>
> On 28 May 2013 20:00, Benoit Chesneau <bc...@gmail.com> wrote:
> > Still +1 on the general idea but thinking more of it we should keep
> > the current Changes and if the proposal pass just amend it with the
> > dynamic results. The main reason for that is that until now we didn't
> > have any rule when it was about writing this commit message. So an
> > automated way will lost a lot of info. Also some commits aren't atomic
> > and lot of changes have been dispatched on 3 3 or more commits.
> > sometimes we even have small typos commit and such.
> >
> > Which conduct me to think that if we go to such changes log then we
> > also need to change the way we handle commits on the master and
> > release. Ie. only atomic or self-described commits should go on
> > master. The point is that without control on the commits the changelog
> > will quickly become useless. Thoughts?
> >
> > - benoit
> >
> > On Mon, May 27, 2013 at 5:44 PM, Benoit Chesneau <bc...@gmail.com>
> wrote:
> >> +1
> >>
> >> On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rn...@apache.org>
> wrote:
> >>> Hi All,
> >>>
> >>> Rather than manually maintaining the NEWS and CHANGES files I'd like
> >>> to save us time by using the output of git log as our release notes
> >>> after 1.3.1.
> >>>
> >>> To make this work we'll need to be better at commit messages. The de
> >>> facto standard for git commit messages is described at
> >>> http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
> >>> and I would like us all to commit to using these guidelines, with some
> >>> clarifications:
> >>>
> >>> 1) The last line of the commit should mention the JIRA ticket.
> >>> 2) The first line does *not* end with punctuation.
> >>>
> >>> Here's a good, albeit sarcastic, example;
> >>>
> >>> --
> >>> Report name of rejected attachment
> >>>
> >>> Some users make requests from inside a black box with a blindfold on
> >>> and their eyes closed and are thus sometimes unaware of the names of
> >>> their own attachments. Let's help these people.
> >>>
> >>> BugzID: 17669
> >>> --
> >>>
> >>> The first line of each log between releases will form the release
> notes.
> >>>
> >>> I'd like to vote on two questions;
> >>>
> >>> 1) That we adopt the git commit message guidelines above.
> >>> 2) That we delete NEWS/CHANGES from master before the next release
> after 1.3.1.
> >>>
> >>> The voting rules are lazy consensus with a 72 hour waiting period. You
> >>> do not have to vote if you agree, though you are welcome to do so. If
> >>> you do vote against I encourage you to include a constructive reason
> >>> or suggest an alternative.
> >>>
> >>>
> >>> B.
>
Re: [VOTE] Git Commit Messages
Posted by Robert Newson <rn...@apache.org>.
Benoit,
Yes, agreed. I think this joins up with Adam's point too. We need to
take more care with commit messages in general, and how features/fixes
are represented in git. We have a thread on the latter already but, to
address your points, we can include this style of commit on the merge
commit for those features/fixes that are better represented as
multiple commits.
I concede the point that we can't ditch NEWS and CHANGES soon, so I'll
retract that question. For 1.4, I suggest we try to base our release
notes from the git log, with whatever modifications we end up making,
and only then decide what our new process looks like.
B.
On 28 May 2013 20:00, Benoit Chesneau <bc...@gmail.com> wrote:
> Still +1 on the general idea but thinking more of it we should keep
> the current Changes and if the proposal pass just amend it with the
> dynamic results. The main reason for that is that until now we didn't
> have any rule when it was about writing this commit message. So an
> automated way will lost a lot of info. Also some commits aren't atomic
> and lot of changes have been dispatched on 3 3 or more commits.
> sometimes we even have small typos commit and such.
>
> Which conduct me to think that if we go to such changes log then we
> also need to change the way we handle commits on the master and
> release. Ie. only atomic or self-described commits should go on
> master. The point is that without control on the commits the changelog
> will quickly become useless. Thoughts?
>
> - benoit
>
> On Mon, May 27, 2013 at 5:44 PM, Benoit Chesneau <bc...@gmail.com> wrote:
>> +1
>>
>> On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rn...@apache.org> wrote:
>>> Hi All,
>>>
>>> Rather than manually maintaining the NEWS and CHANGES files I'd like
>>> to save us time by using the output of git log as our release notes
>>> after 1.3.1.
>>>
>>> To make this work we'll need to be better at commit messages. The de
>>> facto standard for git commit messages is described at
>>> http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
>>> and I would like us all to commit to using these guidelines, with some
>>> clarifications:
>>>
>>> 1) The last line of the commit should mention the JIRA ticket.
>>> 2) The first line does *not* end with punctuation.
>>>
>>> Here's a good, albeit sarcastic, example;
>>>
>>> --
>>> Report name of rejected attachment
>>>
>>> Some users make requests from inside a black box with a blindfold on
>>> and their eyes closed and are thus sometimes unaware of the names of
>>> their own attachments. Let's help these people.
>>>
>>> BugzID: 17669
>>> --
>>>
>>> The first line of each log between releases will form the release notes.
>>>
>>> I'd like to vote on two questions;
>>>
>>> 1) That we adopt the git commit message guidelines above.
>>> 2) That we delete NEWS/CHANGES from master before the next release after 1.3.1.
>>>
>>> The voting rules are lazy consensus with a 72 hour waiting period. You
>>> do not have to vote if you agree, though you are welcome to do so. If
>>> you do vote against I encourage you to include a constructive reason
>>> or suggest an alternative.
>>>
>>>
>>> B.
Re: [VOTE] Git Commit Messages
Posted by Benoit Chesneau <bc...@gmail.com>.
Still +1 on the general idea but thinking more of it we should keep
the current Changes and if the proposal pass just amend it with the
dynamic results. The main reason for that is that until now we didn't
have any rule when it was about writing this commit message. So an
automated way will lost a lot of info. Also some commits aren't atomic
and lot of changes have been dispatched on 3 3 or more commits.
sometimes we even have small typos commit and such.
Which conduct me to think that if we go to such changes log then we
also need to change the way we handle commits on the master and
release. Ie. only atomic or self-described commits should go on
master. The point is that without control on the commits the changelog
will quickly become useless. Thoughts?
- benoit
On Mon, May 27, 2013 at 5:44 PM, Benoit Chesneau <bc...@gmail.com> wrote:
> +1
>
> On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rn...@apache.org> wrote:
>> Hi All,
>>
>> Rather than manually maintaining the NEWS and CHANGES files I'd like
>> to save us time by using the output of git log as our release notes
>> after 1.3.1.
>>
>> To make this work we'll need to be better at commit messages. The de
>> facto standard for git commit messages is described at
>> http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
>> and I would like us all to commit to using these guidelines, with some
>> clarifications:
>>
>> 1) The last line of the commit should mention the JIRA ticket.
>> 2) The first line does *not* end with punctuation.
>>
>> Here's a good, albeit sarcastic, example;
>>
>> --
>> Report name of rejected attachment
>>
>> Some users make requests from inside a black box with a blindfold on
>> and their eyes closed and are thus sometimes unaware of the names of
>> their own attachments. Let's help these people.
>>
>> BugzID: 17669
>> --
>>
>> The first line of each log between releases will form the release notes.
>>
>> I'd like to vote on two questions;
>>
>> 1) That we adopt the git commit message guidelines above.
>> 2) That we delete NEWS/CHANGES from master before the next release after 1.3.1.
>>
>> The voting rules are lazy consensus with a 72 hour waiting period. You
>> do not have to vote if you agree, though you are welcome to do so. If
>> you do vote against I encourage you to include a constructive reason
>> or suggest an alternative.
>>
>>
>> B.
Re: [VOTE] Git Commit Messages
Posted by Alexander Shorin <kx...@gmail.com>.
Good points, +1
--
,,,^..^,,,
On Mon, May 27, 2013 at 7:44 PM, Benoit Chesneau <bc...@gmail.com> wrote:
> +1
>
> On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rn...@apache.org> wrote:
>> Hi All,
>>
>> Rather than manually maintaining the NEWS and CHANGES files I'd like
>> to save us time by using the output of git log as our release notes
>> after 1.3.1.
>>
>> To make this work we'll need to be better at commit messages. The de
>> facto standard for git commit messages is described at
>> http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
>> and I would like us all to commit to using these guidelines, with some
>> clarifications:
>>
>> 1) The last line of the commit should mention the JIRA ticket.
>> 2) The first line does *not* end with punctuation.
>>
>> Here's a good, albeit sarcastic, example;
>>
>> --
>> Report name of rejected attachment
>>
>> Some users make requests from inside a black box with a blindfold on
>> and their eyes closed and are thus sometimes unaware of the names of
>> their own attachments. Let's help these people.
>>
>> BugzID: 17669
>> --
>>
>> The first line of each log between releases will form the release notes.
>>
>> I'd like to vote on two questions;
>>
>> 1) That we adopt the git commit message guidelines above.
>> 2) That we delete NEWS/CHANGES from master before the next release after 1.3.1.
>>
>> The voting rules are lazy consensus with a 72 hour waiting period. You
>> do not have to vote if you agree, though you are welcome to do so. If
>> you do vote against I encourage you to include a constructive reason
>> or suggest an alternative.
>>
>>
>> B.
Re: [VOTE] Git Commit Messages
Posted by Benoit Chesneau <bc...@gmail.com>.
+1
On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rn...@apache.org> wrote:
> Hi All,
>
> Rather than manually maintaining the NEWS and CHANGES files I'd like
> to save us time by using the output of git log as our release notes
> after 1.3.1.
>
> To make this work we'll need to be better at commit messages. The de
> facto standard for git commit messages is described at
> http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
> and I would like us all to commit to using these guidelines, with some
> clarifications:
>
> 1) The last line of the commit should mention the JIRA ticket.
> 2) The first line does *not* end with punctuation.
>
> Here's a good, albeit sarcastic, example;
>
> --
> Report name of rejected attachment
>
> Some users make requests from inside a black box with a blindfold on
> and their eyes closed and are thus sometimes unaware of the names of
> their own attachments. Let's help these people.
>
> BugzID: 17669
> --
>
> The first line of each log between releases will form the release notes.
>
> I'd like to vote on two questions;
>
> 1) That we adopt the git commit message guidelines above.
> 2) That we delete NEWS/CHANGES from master before the next release after 1.3.1.
>
> The voting rules are lazy consensus with a 72 hour waiting period. You
> do not have to vote if you agree, though you are welcome to do so. If
> you do vote against I encourage you to include a constructive reason
> or suggest an alternative.
>
>
> B.
Re: [VOTE] Git Commit Messages
Posted by Noah Slater <ns...@apache.org>.
Oh well. No harm, no foul. The important thing is that we're making
progress and that the right work is happening. There's no indication on
this thread that anyone thinks moving NEWS and CHANGES to docs/ is a bad,
idea, and a good indication that we need to have more of a discussion about
how to maintain the actual release notes. So everything fine. :)
(FWIW, I agree with you. We should not wipe out old changelogs. They are
valuable. And the Git commit messages for that period are going to be very
poor, and not at all a good replacement.)
On 18 July 2013 19:50, Benoit Chesneau <bc...@gmail.com> wrote:
> On Thu, Jul 18, 2013 at 8:49 PM, Noah Slater <ns...@apache.org> wrote:
>
> > Well, this is a VOTE thread, so it's not the appropriate place for a
> > DISCUSSion. I think the conversation about how we maintain our release
> > notes is a very valuable one, and I would like to have that conversation.
> >
> >
> > And the vote has been aborted that's the my point. And I yes I agree we
> should start a new discussion thread.
>
> - benoit
>
>
> > On 18 July 2013 19:41, Benoit Chesneau <bc...@gmail.com> wrote:
> >
> > > On Thu, Jul 18, 2013 at 8:35 PM, Noah Slater <ns...@apache.org>
> wrote:
> > >
> > > > NEWS and CHANGES need to be moved to the docs one way or another, so
> > > Dirkan
> > > > is doing us a favour by undertaking that effort. If you'd like to
> > restart
> > > > the discussion as to how we populate our changelog, please start a
> new
> > > > thread.
> > > >
> > > >
> > > Please take the time to read this thread. Also I don't dismiss the work
> > > done by djc in any case. I am asking an honest question and you don't
> > > answer to it. Also can we continue the discussion on the right thread?
> Ie
> > > the commit one?
> > >
> > > Thanks.
> > >
> > > - benoit
> > >
> >
> >
> >
> > --
> > NS
> >
>
--
NS
Re: [VOTE] Git Commit Messages
Posted by Benoit Chesneau <bc...@gmail.com>.
On Thu, Jul 18, 2013 at 8:49 PM, Noah Slater <ns...@apache.org> wrote:
> Well, this is a VOTE thread, so it's not the appropriate place for a
> DISCUSSion. I think the conversation about how we maintain our release
> notes is a very valuable one, and I would like to have that conversation.
>
>
> And the vote has been aborted that's the my point. And I yes I agree we
should start a new discussion thread.
- benoit
> On 18 July 2013 19:41, Benoit Chesneau <bc...@gmail.com> wrote:
>
> > On Thu, Jul 18, 2013 at 8:35 PM, Noah Slater <ns...@apache.org> wrote:
> >
> > > NEWS and CHANGES need to be moved to the docs one way or another, so
> > Dirkan
> > > is doing us a favour by undertaking that effort. If you'd like to
> restart
> > > the discussion as to how we populate our changelog, please start a new
> > > thread.
> > >
> > >
> > Please take the time to read this thread. Also I don't dismiss the work
> > done by djc in any case. I am asking an honest question and you don't
> > answer to it. Also can we continue the discussion on the right thread? Ie
> > the commit one?
> >
> > Thanks.
> >
> > - benoit
> >
>
>
>
> --
> NS
>
Re: [VOTE] Git Commit Messages
Posted by Noah Slater <ns...@apache.org>.
Well, this is a VOTE thread, so it's not the appropriate place for a
DISCUSSion. I think the conversation about how we maintain our release
notes is a very valuable one, and I would like to have that conversation.
On 18 July 2013 19:41, Benoit Chesneau <bc...@gmail.com> wrote:
> On Thu, Jul 18, 2013 at 8:35 PM, Noah Slater <ns...@apache.org> wrote:
>
> > NEWS and CHANGES need to be moved to the docs one way or another, so
> Dirkan
> > is doing us a favour by undertaking that effort. If you'd like to restart
> > the discussion as to how we populate our changelog, please start a new
> > thread.
> >
> >
> Please take the time to read this thread. Also I don't dismiss the work
> done by djc in any case. I am asking an honest question and you don't
> answer to it. Also can we continue the discussion on the right thread? Ie
> the commit one?
>
> Thanks.
>
> - benoit
>
--
NS
Re: [VOTE] Git Commit Messages
Posted by Benoit Chesneau <bc...@gmail.com>.
On Thu, Jul 18, 2013 at 8:35 PM, Noah Slater <ns...@apache.org> wrote:
> NEWS and CHANGES need to be moved to the docs one way or another, so Dirkan
> is doing us a favour by undertaking that effort. If you'd like to restart
> the discussion as to how we populate our changelog, please start a new
> thread.
>
>
Please take the time to read this thread. Also I don't dismiss the work
done by djc in any case. I am asking an honest question and you don't
answer to it. Also can we continue the discussion on the right thread? Ie
the commit one?
Thanks.
- benoit
Re: [VOTE] Git Commit Messages
Posted by Noah Slater <ns...@apache.org>.
NEWS and CHANGES need to be moved to the docs one way or another, so Dirkan
is doing us a favour by undertaking that effort. If you'd like to restart
the discussion as to how we populate our changelog, please start a new
thread.
On 18 July 2013 19:12, Benoit Chesneau <bc...@gmail.com> wrote:
> On Thursday, July 18, 2013, Noah Slater wrote:
>
> > Benoit, your concerns are orthogonal to the location of the
> documentation.
> >
> >
> my concern is not about the doc but about the news and changes files that
> have been removed. cf the thread about it.
>
>
>
>
>
> > Dirkjan, thanks for taking care of this! Long overdue.
> >
> >
> > On 18 July 2013 13:29, Benoit Chesneau <bchesneau@gmail.com<javascript:;>>
> > wrote:
> >
> > > On Thu, Jul 18, 2013 at 2:21 PM, Dirkjan Ochtman <dirkjan@ochtman.nl
> <javascript:;>
> > >
> > > wrote:
> > >
> > > > On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rnewson@apache.org
> <javascript:;>
> > >
> > > wrote:
> > > > > I'd like to vote on two questions;
> > > > >
> > > > > 1) That we adopt the git commit message guidelines above.
> > > > > 2) That we delete NEWS/CHANGES from master before the next release
> > > after
> > > > 1.3.1.
> > > > >
> > > > > The voting rules are lazy consensus with a 72 hour waiting period.
> > You
> > > > > do not have to vote if you agree, though you are welcome to do so.
> If
> > > > > you do vote against I encourage you to include a constructive
> reason
> > > > > or suggest an alternative.
> > > >
> > > > Based on the votes for proposal 2 (+1 all around, one abstainment),
> > > > I'm going to delete NEWS and CHANGES from master and make sure the
> > > > limited stuff is there now is instead reflected in the docs release
> > > > history chapter.
> > > >
> > > > Cheers,
> > > >
> > > > Dirkjan
> > > >
> > >
> > > well if i reread the thread, the question was retracted..... imo for
> 1,4,
> > > the best idea is to extract the logs from the commit and add them on
> top
> > pf
> > > the changes.
> > >
> > > - benoit
> > >
> >
> >
> >
> > --
> > NS
> >
>
--
NS
Re: [VOTE] Git Commit Messages
Posted by Benoit Chesneau <bc...@gmail.com>.
On Thursday, July 18, 2013, Noah Slater wrote:
> Benoit, your concerns are orthogonal to the location of the documentation.
>
>
my concern is not about the doc but about the news and changes files that
have been removed. cf the thread about it.
> Dirkjan, thanks for taking care of this! Long overdue.
>
>
> On 18 July 2013 13:29, Benoit Chesneau <bchesneau@gmail.com <javascript:;>>
> wrote:
>
> > On Thu, Jul 18, 2013 at 2:21 PM, Dirkjan Ochtman <dirkjan@ochtman.nl<javascript:;>
> >
> > wrote:
> >
> > > On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rnewson@apache.org<javascript:;>
> >
> > wrote:
> > > > I'd like to vote on two questions;
> > > >
> > > > 1) That we adopt the git commit message guidelines above.
> > > > 2) That we delete NEWS/CHANGES from master before the next release
> > after
> > > 1.3.1.
> > > >
> > > > The voting rules are lazy consensus with a 72 hour waiting period.
> You
> > > > do not have to vote if you agree, though you are welcome to do so. If
> > > > you do vote against I encourage you to include a constructive reason
> > > > or suggest an alternative.
> > >
> > > Based on the votes for proposal 2 (+1 all around, one abstainment),
> > > I'm going to delete NEWS and CHANGES from master and make sure the
> > > limited stuff is there now is instead reflected in the docs release
> > > history chapter.
> > >
> > > Cheers,
> > >
> > > Dirkjan
> > >
> >
> > well if i reread the thread, the question was retracted..... imo for 1,4,
> > the best idea is to extract the logs from the commit and add them on top
> pf
> > the changes.
> >
> > - benoit
> >
>
>
>
> --
> NS
>
Re: [VOTE] Git Commit Messages
Posted by Noah Slater <ns...@apache.org>.
Benoit, your concerns are orthogonal to the location of the documentation.
Dirkjan, thanks for taking care of this! Long overdue.
On 18 July 2013 13:29, Benoit Chesneau <bc...@gmail.com> wrote:
> On Thu, Jul 18, 2013 at 2:21 PM, Dirkjan Ochtman <di...@ochtman.nl>
> wrote:
>
> > On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rn...@apache.org>
> wrote:
> > > I'd like to vote on two questions;
> > >
> > > 1) That we adopt the git commit message guidelines above.
> > > 2) That we delete NEWS/CHANGES from master before the next release
> after
> > 1.3.1.
> > >
> > > The voting rules are lazy consensus with a 72 hour waiting period. You
> > > do not have to vote if you agree, though you are welcome to do so. If
> > > you do vote against I encourage you to include a constructive reason
> > > or suggest an alternative.
> >
> > Based on the votes for proposal 2 (+1 all around, one abstainment),
> > I'm going to delete NEWS and CHANGES from master and make sure the
> > limited stuff is there now is instead reflected in the docs release
> > history chapter.
> >
> > Cheers,
> >
> > Dirkjan
> >
>
> well if i reread the thread, the question was retracted..... imo for 1,4,
> the best idea is to extract the logs from the commit and add them on top pf
> the changes.
>
> - benoit
>
--
NS
Re: [VOTE] Git Commit Messages
Posted by Benoit Chesneau <bc...@gmail.com>.
On Thu, Jul 18, 2013 at 2:21 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rn...@apache.org> wrote:
> > I'd like to vote on two questions;
> >
> > 1) That we adopt the git commit message guidelines above.
> > 2) That we delete NEWS/CHANGES from master before the next release after
> 1.3.1.
> >
> > The voting rules are lazy consensus with a 72 hour waiting period. You
> > do not have to vote if you agree, though you are welcome to do so. If
> > you do vote against I encourage you to include a constructive reason
> > or suggest an alternative.
>
> Based on the votes for proposal 2 (+1 all around, one abstainment),
> I'm going to delete NEWS and CHANGES from master and make sure the
> limited stuff is there now is instead reflected in the docs release
> history chapter.
>
> Cheers,
>
> Dirkjan
>
well if i reread the thread, the question was retracted..... imo for 1,4,
the best idea is to extract the logs from the commit and add them on top pf
the changes.
- benoit
Re: [VOTE] Git Commit Messages
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rn...@apache.org> wrote:
> I'd like to vote on two questions;
>
> 1) That we adopt the git commit message guidelines above.
> 2) That we delete NEWS/CHANGES from master before the next release after 1.3.1.
>
> The voting rules are lazy consensus with a 72 hour waiting period. You
> do not have to vote if you agree, though you are welcome to do so. If
> you do vote against I encourage you to include a constructive reason
> or suggest an alternative.
Based on the votes for proposal 2 (+1 all around, one abstainment),
I'm going to delete NEWS and CHANGES from master and make sure the
limited stuff is there now is instead reflected in the docs release
history chapter.
Cheers,
Dirkjan
Re: [VOTE] Git Commit Messages
Posted by Randall Leeds <ra...@gmail.com>.
On Tue, May 28, 2013 at 1:20 AM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Tue, May 28, 2013 at 10:10 AM, Robert Newson <rn...@apache.org> wrote:
>> 1) We're all for including the JIRA ticket, for traceability, the
>> question I have is why put that in the summary line?
>
> Because it makes things easier for people trawling through high-level
> commit logs (e.g. me when I start to edit change logs for the release,
> but also non-committer devs following our Github repo etc.).
COUCHDB-* is still in the full commit message.
I think the two of us can devise a merge procedure that will make this
easier to manage for committers.
We also have JIRA, on which people can always subscribe to bugs.
Therefore, I'm with rnewson on wanting the full 50 characters for the summary.
+1 on the message format
+1 on moving CHANGES/NEWS to the docs on master
>
>> 2) There might be a classification scheme that makes sense but, since
>> we agree the present one doesn't, can we ditch it until someone
>> proposes a better one?
>
> Fine with me.
+1
Re: [VOTE] Git Commit Messages
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Tue, May 28, 2013 at 10:10 AM, Robert Newson <rn...@apache.org> wrote:
> 1) We're all for including the JIRA ticket, for traceability, the
> question I have is why put that in the summary line?
Because it makes things easier for people trawling through high-level
commit logs (e.g. me when I start to edit change logs for the release,
but also non-committer devs following our Github repo etc.).
> 2) There might be a classification scheme that makes sense but, since
> we agree the present one doesn't, can we ditch it until someone
> proposes a better one?
Fine with me.
Cheers,
Dirkjan
Re: [VOTE] Git Commit Messages
Posted by Robert Newson <rn...@apache.org>.
1) We're all for including the JIRA ticket, for traceability, the
question I have is why put that in the summary line?
2) There might be a classification scheme that makes sense but, since
we agree the present one doesn't, can we ditch it until someone
proposes a better one?
B.
On 28 May 2013 08:50, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Mon, May 27, 2013 at 7:14 PM, Robert Newson <rn...@apache.org> wrote:
>> If people want more than the one line summary, they can get the full
>> details from the commit message, so I'm not keen on doing extra work
>> (and commits) to generate redundant information. I'm -1 on adding the
>> section and jira information into the summary. It's already quite
>> short and these two items use precious characters. Since they can both
>> be put in the commit message later, it seems unnecessary to put them
>> in the summary (what's a summary if it contains every detail of the
>> commit? :)).
>
> I think the bug identifiers in particular are pretty useful for
> developers, and about 5 characters isn't that much (just omit the
> silly COUCHDB- prefix). The section may not always make sense, but I
> think it's useful communication (e.g. most of you can happily ignore
> commit email where the commit message starts with "docs:").
>
>> A big part of the motivation here is to avoid any release-time effort
>> in generating a change log at all since this is administrivia that can
>> delay releases. The idea being to do it piecemeal as we develop the
>> software. I'm interested if anyone would find it valuable to include
>> more than we've included in NEWS/CHANGES to date (and, more
>> importantly, if those people are prepared to do the work).
>
> I understand that, and I think better commit messages would go a long
> way here. I personally think the change log should still be edited by
> hand, and I'm happy to spend some time each month doing that. Though
> it should be in the nice documentation, not in NEWS/CHANGES.
>
>> A final point, I'm not sure the subsystem breakdown from CHANGES is
>> all that useful. It's certainly extra work for the author but does
>> that translate into a benefit for the user? Does anyone need to be
>> told that "Tolerate missing source and target fields in _replicator
>> docs" applies to the Replicator subsystem or that "Fix bug in WARN
>> level logging from 1.3.0" applies to the logging subsystem? It's
>> clearly redundant to me, and a burden to us. In my opinion someone
>> needs to make a strong case for continuing with that scheme, rather
>> than the inverse.
>
> I agree that the subsystems as currently used in CHANGES (and the
> change log) isn't that useful. That doesn't mean that there isn't some
> classification scheme that *does* make sense, of course (e.g. API vs.
> internals vs. configuration?).
>
> Cheers,
>
> Dirkjan
Re: [VOTE] Git Commit Messages
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Mon, May 27, 2013 at 7:14 PM, Robert Newson <rn...@apache.org> wrote:
> If people want more than the one line summary, they can get the full
> details from the commit message, so I'm not keen on doing extra work
> (and commits) to generate redundant information. I'm -1 on adding the
> section and jira information into the summary. It's already quite
> short and these two items use precious characters. Since they can both
> be put in the commit message later, it seems unnecessary to put them
> in the summary (what's a summary if it contains every detail of the
> commit? :)).
I think the bug identifiers in particular are pretty useful for
developers, and about 5 characters isn't that much (just omit the
silly COUCHDB- prefix). The section may not always make sense, but I
think it's useful communication (e.g. most of you can happily ignore
commit email where the commit message starts with "docs:").
> A big part of the motivation here is to avoid any release-time effort
> in generating a change log at all since this is administrivia that can
> delay releases. The idea being to do it piecemeal as we develop the
> software. I'm interested if anyone would find it valuable to include
> more than we've included in NEWS/CHANGES to date (and, more
> importantly, if those people are prepared to do the work).
I understand that, and I think better commit messages would go a long
way here. I personally think the change log should still be edited by
hand, and I'm happy to spend some time each month doing that. Though
it should be in the nice documentation, not in NEWS/CHANGES.
> A final point, I'm not sure the subsystem breakdown from CHANGES is
> all that useful. It's certainly extra work for the author but does
> that translate into a benefit for the user? Does anyone need to be
> told that "Tolerate missing source and target fields in _replicator
> docs" applies to the Replicator subsystem or that "Fix bug in WARN
> level logging from 1.3.0" applies to the logging subsystem? It's
> clearly redundant to me, and a burden to us. In my opinion someone
> needs to make a strong case for continuing with that scheme, rather
> than the inverse.
I agree that the subsystems as currently used in CHANGES (and the
change log) isn't that useful. That doesn't mean that there isn't some
classification scheme that *does* make sense, of course (e.g. API vs.
internals vs. configuration?).
Cheers,
Dirkjan
Re: [VOTE] Git Commit Messages
Posted by Robert Newson <rn...@apache.org>.
If people want more than the one line summary, they can get the full
details from the commit message, so I'm not keen on doing extra work
(and commits) to generate redundant information. I'm -1 on adding the
section and jira information into the summary. It's already quite
short and these two items use precious characters. Since they can both
be put in the commit message later, it seems unnecessary to put them
in the summary (what's a summary if it contains every detail of the
commit? :)).
A big part of the motivation here is to avoid any release-time effort
in generating a change log at all since this is administrivia that can
delay releases. The idea being to do it piecemeal as we develop the
software. I'm interested if anyone would find it valuable to include
more than we've included in NEWS/CHANGES to date (and, more
importantly, if those people are prepared to do the work).
A final point, I'm not sure the subsystem breakdown from CHANGES is
all that useful. It's certainly extra work for the author but does
that translate into a benefit for the user? Does anyone need to be
told that "Tolerate missing source and target fields in _replicator
docs" applies to the Replicator subsystem or that "Fix bug in WARN
level logging from 1.3.0" applies to the logging subsystem? It's
clearly redundant to me, and a burden to us. In my opinion someone
needs to make a strong case for continuing with that scheme, rather
than the inverse.
B.
On 27 May 2013 17:05, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rn...@apache.org> wrote:
>> Rather than manually maintaining the NEWS and CHANGES files I'd like
>> to save us time by using the output of git log as our release notes
>> after 1.3.1.
>>
>> To make this work we'll need to be better at commit messages. The de
>> facto standard for git commit messages is described at
>> http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
>> and I would like us all to commit to using these guidelines, with some
>> clarifications:
>>
>> 1) The last line of the commit should mention the JIRA ticket.
>> 2) The first line does *not* end with punctuation.
>>
>> Here's a good, albeit sarcastic, example;
>>
>> --
>> Report name of rejected attachment
>>
>> Some users make requests from inside a black box with a blindfold on
>> and their eyes closed and are thus sometimes unaware of the names of
>> their own attachments. Let's help these people.
>>
>> BugzID: 17669
>> --
>>
>> The first line of each log between releases will form the release notes.
>
> Hmm, I don't fully agree.
>
> Most importantly, commit messages are a means to communicate to
> developers (both other developers and ourselves in the future). Change
> logs are used to communicate with users. Therefore, tone and contents
> for those two pieces of text should often be different. Therefore, I
> don't think we should rely on commit messages to generate change logs,
> although they are definitely a good starting point and adding extra
> stuff after the first line in the commit message is still very useful
> while writing the change logs.
>
> I would also like to slightly change the proposed structure of the
> commit messages, to include the ticket number in the first line and a
> mandatory tag to indicate a subsystem that the commit is most relevant
> to. E.g.:
>
> "Attachments: report name of rejected attachment (#17669)"
>
>> I'd like to vote on two questions;
>>
>> 1) That we adopt the git commit message guidelines above.
>> 2) That we delete NEWS/CHANGES from master before the next release after 1.3.1.
>>
>> The voting rules are lazy consensus with a 72 hour waiting period. You
>> do not have to vote if you agree, though you are welcome to do so. If
>> you do vote against I encourage you to include a constructive reason
>> or suggest an alternative.
>
> I vote +1 on deleting NEWS/CHANGES, but rather than generating these
> from commit messages, we add change logs to the Sphinx-based docs. I
> vote -1 on your git commit message guidelines, and propose my
> suggested alternative instead.
>
> Cheers,
>
> Dirkjan
Re: [VOTE] Git Commit Messages
Posted by Dirkjan Ochtman <di...@ochtman.nl>.
On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rn...@apache.org> wrote:
> Rather than manually maintaining the NEWS and CHANGES files I'd like
> to save us time by using the output of git log as our release notes
> after 1.3.1.
>
> To make this work we'll need to be better at commit messages. The de
> facto standard for git commit messages is described at
> http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
> and I would like us all to commit to using these guidelines, with some
> clarifications:
>
> 1) The last line of the commit should mention the JIRA ticket.
> 2) The first line does *not* end with punctuation.
>
> Here's a good, albeit sarcastic, example;
>
> --
> Report name of rejected attachment
>
> Some users make requests from inside a black box with a blindfold on
> and their eyes closed and are thus sometimes unaware of the names of
> their own attachments. Let's help these people.
>
> BugzID: 17669
> --
>
> The first line of each log between releases will form the release notes.
Hmm, I don't fully agree.
Most importantly, commit messages are a means to communicate to
developers (both other developers and ourselves in the future). Change
logs are used to communicate with users. Therefore, tone and contents
for those two pieces of text should often be different. Therefore, I
don't think we should rely on commit messages to generate change logs,
although they are definitely a good starting point and adding extra
stuff after the first line in the commit message is still very useful
while writing the change logs.
I would also like to slightly change the proposed structure of the
commit messages, to include the ticket number in the first line and a
mandatory tag to indicate a subsystem that the commit is most relevant
to. E.g.:
"Attachments: report name of rejected attachment (#17669)"
> I'd like to vote on two questions;
>
> 1) That we adopt the git commit message guidelines above.
> 2) That we delete NEWS/CHANGES from master before the next release after 1.3.1.
>
> The voting rules are lazy consensus with a 72 hour waiting period. You
> do not have to vote if you agree, though you are welcome to do so. If
> you do vote against I encourage you to include a constructive reason
> or suggest an alternative.
I vote +1 on deleting NEWS/CHANGES, but rather than generating these
from commit messages, we add change logs to the Sphinx-based docs. I
vote -1 on your git commit message guidelines, and propose my
suggested alternative instead.
Cheers,
Dirkjan