Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Received-SPF: pass (athena.apache.org: domain of djc.ochtman@gmail.com
 designates 209.85.160.53 as permitted sender)
MIME-Version: 1.0
Sender: djc.ochtman@gmail.com
In-Reply-To: 
 <CABvT1DEMMgjVrheEnd5QbnKjYkJ13xCev8thvPRdHU54yZcSpQ@mail.gmail.com>
References: 
 <CABvT1DEMMgjVrheEnd5QbnKjYkJ13xCev8thvPRdHU54yZcSpQ@mail.gmail.com>
From: Dirkjan Ochtman <dirkjan@ochtman.nl>
Date: Mon, 27 May 2013 18:05:42 +0200
Message-ID: 
 <CAKmKYaAdNCPVjksvU9guQAAbZq8eALGbdW9t7AQj3NxGoxwMEg@mail.gmail.com>
Subject: Re: [VOTE] Git Commit Messages
To: "dev@couchdb.apache.org" <dev@couchdb.apache.org>
Content-Type: text/plain; charset=UTF-8

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