Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
MIME-Version: 1.0
In-Reply-To: 
 <CAKmKYaAdNCPVjksvU9guQAAbZq8eALGbdW9t7AQj3NxGoxwMEg@mail.gmail.com>
References: 
 <CABvT1DEMMgjVrheEnd5QbnKjYkJ13xCev8thvPRdHU54yZcSpQ@mail.gmail.com>
	<CAKmKYaAdNCPVjksvU9guQAAbZq8eALGbdW9t7AQj3NxGoxwMEg@mail.gmail.com>
Date: Mon, 27 May 2013 18:14:42 +0100
Message-ID: 
 <CABvT1DH4=HM36iTOiiRTzzhacCXVTLjK4Zh9C_t+Wqg0Fe10xQ@mail.gmail.com>
Subject: Re: [VOTE] Git Commit Messages
From: Robert Newson <rnewson@apache.org>
To: "dev@couchdb.apache.org" <dev@couchdb.apache.org>
Content-Type: text/plain; charset=ISO-8859-1

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 <dirkjan@ochtman.nl> wrote:
> On Mon, May 27, 2013 at 5:42 PM, Robert Newson <rnewson@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