[bind10-dev] Changes Log

[Shane Kerr]

All,

On Mon, 2010-04-05 at 12:55 -0700, JINMEI Tatuya / 神明達哉 wrote:
> At Thu, 1 Apr 2010 11:28:23 -0500 (CDT),
> "Jeremy C. Reed" <jreed at isc.org> wrote:
> > 
> > We need to decide on the format or what to provide for a CHANGES file 
> > and for release notes?
> > 
> > (I was hoping to talk about this on our phone call.)
> > 
> > Should we go with existing BIND 9 CHANGES style? This means we will have 
> > to write them.
> > 
> > Should we create it automatically from svn log history? That will work 
> > but some entries may be too verbose or not verbose enough.
> > 
> > The plan for now is to have a changes log included in the next tar ball 
> > and in the release announcement.
> 
> I've not fully thought about it, but I'm afraid the current style of
> BIND9 change logs is not very useful:
> 
> - the logs are often "too concise", and it wouldn't always be easy for
>   a user to understand the severity of a bug or relevance to problems
>   they're having.
> - the definition of change categories ("bug", "func" etc) is not clear
> - reference numbers to bug tickets (RT #xxxx) aren't useful for
>   ordinary users because the BIND9 RT is closed
> 
> Some of the problems will be automatically solved in BIND10 due to its
> nature of "broader openness", but some others may not be trivial to
> address.  It might also depend on the expected target of the change
> logs.  If it's mainly for users, we should probably provide more
> informative logs; if it's mainly for developers, a simple one-line
> summary with a reference to the bug ticket may suffice.

I think the main consumers of change logs are system administrators,
followed by distribution vendors. (People working on distributions
probably read them more carefully, but there are fewer of them.) So, we
should probably target those people.

I much prefer the DHCP-style changelogs:

        http://www.isc.org/files/release-notes/402.html

Which has things like:

        "Fixed a bug where a time difference of greater than 60 seconds
        between a failover pair could cause the primary to crash on
        contact with the secondary. Thanks to a patch from Steinar
        Haug."

This is pretty clear, and actually helpful without looking at the source
code. The main improvement we could add would be a reference to a set of
Trac tickets and/or Subversion commits.

I do like BIND 10's attempt to classify changes as
bug/enhancement/whatever. That might be nice to preserve.

--
Shane