lkml.org 
[lkml]   [2010]   [Jan]   [13]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: Changelog quality (was Re: [PATCH] uwb: make USB device id constant)
> 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.

julia


\
 
 \ /
  Last update: 2010-01-13 16:41    [from the cache]
©2003-2011 Jasper Spaans. Advertise on this site