[bind10-dev] Changes Log

[JINMEI Tatuya / 神明達哉]

(Replying to an old message)

At Tue, 06 Apr 2010 13:07:14 +0200,
Shane Kerr <shane at isc.org> wrote:

> > 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

[snip]

> 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.

I've happened to fix a small bug (trac #177) and thought it would be a
good opportunity to start our changelogs.

This is an example changelog entry for this fix:

================================ from here ==============================
   1.	[bug]		jinmei
	lib/dns: parameter validation of Name::split() was not sufficient,
	and invalid parameters could cause integer overflow and make the
	library crash. (Trac #177, svn r1806)

LEGEND
[bug] general bug fix.  This is generally a backward compatible change,
	unless it's deemed to be impossible or very hard to keep
	compatibility to fix the bug.
[doc] update to documentation.  This shouldn't change run time behavior.
[func] new feature.  In some cases this may be a backward incompatible
	change, which would require a bump of major version.
[security] security hole fix.  This is no different than a general bug fix
	except that it will be handled as confidential and will cause 
	security patch releases.
================================  to here  ==============================

This is similar to BIND 9's CHANGES entry, but is different in the
following points:

- it has the corresponding svn changeset (to trunk).  this may not
  always be feasible, so I'd consider this optional.
- it shows the developer committing to the change.  I'm not
  necessarily pushing this style, but thought it might be better in
  that we give clear credit to the contribution, especially because
  BIND 10 is (and will be hopefully) multi organization effort,
  perhaps also with individual committers in future.
- it shows a brief legend of change "categories".

The description of the change is not very detailed as the DHCP-style
example.  In fact, the DHCP ones are "release notes", rather than a
mere "log of changes".  I tend to agree that it's nice to provide a
more readable release note containing details of major changes (BIND
9's release notes are not very good in this sense), but I think it
makes sense to have a relatively concise list of changes.  So, in the
above proposal I tried to avoid being too detailed.

I know the overhead may become an issue if we try to provide both this
style of change logs and more detailed release notes.  If it turns out
to be the case we may consider consolidating those.

Comments?  (Can I commit this experimental entry to trunk?)

---
JINMEI, Tatuya