[bind10-dev] style for changelog (was Re: BIND 10 #381: TSIG key and key ring classes)

[JINMEI Tatuya / 神明達哉]

At Tue, 19 Oct 2010 12:26:43 -0500 (CDT),
"Jeremy C. Reed" <jreed at isc.org> wrote:
> 
> >  This is the proposed changelog entry.
> > 
> >  {{{
> >    112.? [func]          jinmei
> >          src/lib/dns: introduced two new classes, TSIGKey and TSIGKeyRing,
> >          to manage TSIG keys. (Trac #381, svn rTBD)
> >  }}}
> 
> Is the changelog primary audience: developers, admins, packagers, 
> other? We may need to document a short wiki page to define the audience.

I slightly recalled we discussed this before, but I don't remember the
conclusion (if any).

> My concern above is with term "classes" and maybe how could this be 
> slightly reworded for an DNS administrator that is reading the 
> changelog.

I paused when I wrote the proposed text, and considered whether I
could improve it further.  I didn't see the need for it, so I
submitted the original text.

This is not to insist I was correct, and I'm happy to improve it, but
even after I saw your message I don't understand what's specifically
wrong with "classes" and therefore I have no idea about how it could
be reworded.  If you have specific suggestions I'd love to hear it.

In general, as you hinted, we probably need a specific guideline for
changelog entries that would include
 - the intended audience
 - specific points that should be covered by each changelog entry
 - when we use the "*" mark
 - an example of bad entry and how it should be improved according to
   the above points

BTW, "administrators" won't be interested in this specific changelog
entry, because it's just one intermediate step of supporting the whole
TSIG feature, and this specific change doesn't provide any interface
for administrators to play with.  Did I have to explicitly say that
by, e.g. "The TSIG support is still incomplete, and is not yet
available for administrators"?

---
JINMEI, Tatuya