Re: Changelog quality

[Stefan Richter <stefanr@s5r6.in-berlin.de>]

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,

This "used a script to change down/up to mutexes" surely was meant to
convey that the submitter performed a mass change on code that he is not
particularly familiar with or frequently works with himself, i.e. it was
a mostly mechanical change in contrast to how proposed changes are
usually developed.

Semaphore to mutex conversions are/have been not as trivial as for
example a marking of an ID table as const.  Hence those hints that this
was a mostly mechanical conversion (certainly with some checking
afterwards) usefully put the submission into perspective for reviewers.
This information may also be useful after commit, hence it is good for
the SCM's changelog.

The find-and-replace macro itself and the processor which ran that macro
during the development of such a sem2mutex change is entirely uninteresting.

> not all down/ups were changed to mutexes,

If that was unexplained, the it was probably an unintended result of the
mechanical conversion by someone who does not have a deeper personal
investment in the affected code, or simply missed something for whatever
reason.

If it was by mistake, inclusion of the find-and-replace script into the
patch posting *after the --- delimiter* might have increased the chance
that a patch reviewer becomes aware of a possible error source
(inadequate match patterns...).  So that could be useful during review
before commit, but not so much if the change is revisited some time
after commit.

> and in short there was no understandable trace of why the change 
> was made where it was.

Then that changelog was bad since it missed to document the "Why", which
is one of the most important parts of a changelog.

> Perhaps that is a pathological example, but it is 
> not necessarily obvious in advance what needs precise documentation and 
> what does not.

Granted, it is subjective.  The perfect changelog which is ideal for
every possible audience does not exist.
-- 
Stefan Richter
-=====-==-=- ---= -==-=
http://arcgraph.de/sr/