Re: Changelog quality (was Re: [PATCH] uwb: make USB device id constant)

[Andy Isaacson <adi@hexapodia.org>]

On Wed, Jan 13, 2010 at 04:38:22PM +0100, Julia Lawall wrote:
> > When you write a changelog, keep your audience in mind:
> > 
> >   - Developers, distributors, advanced users want to learn what a new
> >     release brings.  (OK, this audience stops reading after the initial
> >     headline of a "make XYZ table constant" commit.  Which just means
> >     that all the rest of the changelog is fluff that can be omitted.)
> > 
> >   - Developers, maintainers etc. want to understand years later why the
> >     code is how it is.  (For them, a commit like that is sufficiently
> >     described by the headline as well.)
> 
> Not surprisingly, I don't agree about this one.  I recall a series of 
> patches that said something like "used a script to change down/up to 
> mutexes".  The script wasn't included, not all down/ups were changed to 
> mutexes, and in short there was no understandable trace of why the change 
> was made where it was.  Perhaps that is a pathological example, but it is 
> not necessarily obvious in advance what needs precise documentation and 
> what does not.

I agree with Julia, at least in some cases.  Having the semantic patch
present when it's 5 or 10 lines long and clearly explains the intended
change is incredibly valuable for review.  Sometimes, the script is the
clearest way to indicate your intent -- I'd much rather see a changelog
that says "s/FOO/BAR/g" than "Change FOO to BAR everywhere".

For example, look at 5d66fe92.  The semantic patch is blissfully,
incredibly clear.  It makes the sun shine down through the clouds, the
birds sing, and the kzalloc align.  It's 10 lines long and is quite
intuitive and explanatory.  In that case, I think it's clear that the
spatch is worth the changelog space it takes up, even though the
changelog is larger than the diff by quite a margin.

On the other hand, the patch that started this thread is a
counterexample, to me.  The correctness of the constification is only
tenuously attested, for me at least, by the semantic patch.  The spatch
is really long compared to the diff, and complicated to read.

So, I think it's a balancing act.  I've been very happy to see spatches
in some of Julia's posts, and I've also found some of the more
voluminous spatches in changelogs to be more noise than signal.

-andy