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    [W:0.027 / U:122.840 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site