Deriving release notes from git commit messages - Mailing list pgsql-hackers

From Greg Smith
Subject Deriving release notes from git commit messages
Date
Msg-id 4E04C63A.8010309@2ndQuadrant.com
Whole thread Raw
Responses Re: Deriving release notes from git commit messages
Re: Deriving release notes from git commit messages
List pgsql-hackers
There's been a steady flow of messages on pgsql-advocacy since last 
month (threads "Crediting sponsors in release notes?" and "Crediting 
reviewers & bug-reporters in the release notes") talking about who/how 
should receive credited for their work on PostgreSQL.  That discussion 
seems to be me heading in one inevitable direction:  it's not going to 
be possible to make everyone happy unless there's a way to track all of 
these things for each feature added to PostgreSQL:

-Short description for the release notes
-Feature author(s)
-Reviewers and bug reporters
-Sponsors
-Main git commit adding the feature

Now, this is clearly the job for a tool, because the idea that any 
person capable of doing this work will actually do it is 
laughable--everyone qualified is too busy.  It strikes me however that 
the current production of the release notes is itself a time consuming 
and error-prone process that could also be improved by automation.  I 
had an idea for pushing forward both these at once.

Committers here are pretty good at writing terse but clear summaries of 
new features when they are added.  These are generally distilled further 
for the release notes.  It strikes me that a little decoration of commit 
messages might go a long way toward saving time in a few areas here.  
I'll pick a simple easy example I did to demonstrate; I wrote a small 
optimization to commit_delay committed at 
http://archives.postgresql.org/message-id/E1PQP72-0001uS-0d@gemulon.postgresql.org

This made its way into the release notes like this:
  Improve performance of commit_siblings (Greg Smith)  This allows the use of commit_siblings with less overhead.

What if the commit message had been decorated like this?
  Feature:  Improve performance of commit_siblings
  Optimize commit_siblings in two ways to improve group commit.  First, avoid scanning the whole ProcArray once we know
there...

With that simple addition, two things become possible:

-Generating a first draft of the release notes for a new version could 
turn into a script that parses the git commit logs, which has gotta save 
somebody a whole lot of time each release that goes into the first draft 
of the release notes.
-All of these other ways to analyze of the contributors would be much 
easier to maintain.  A little "Author:" decoration to that section of 
each commit would probably be welcome too.

I'm sure someone is going to reply to this suggesting some git metadata 
is the right way to handle this, but that seems like overkill to me.  I 
think there's enough committer time gained in faster release note 
generation for this decoration to payback its overhead, which is 
important to me--I'd want a change here to net close to zero for 
committers.  And the fact that it would also allow deriving all this 
other data makes it easier to drive the goals rising out of advocacy 
forward too.

-- 
Greg Smith   2ndQuadrant US    greg@2ndQuadrant.com   Baltimore, MD
PostgreSQL Training, Services, and 24x7 Support  www.2ndQuadrant.us




pgsql-hackers by date:

Previous
From: Robert Haas
Date:
Subject: Re: News on Clang
Next
From: Alvaro Herrera
Date:
Subject: Re: Re: starting to review the Extend NOT NULL representation to pg_constraint patch