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

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

Németh Márton wrote:
> David Vrabel írta:
>> Can you please not include this as part of the changelog in future?  You
>> may include it after the '---' if you wish.
> 
> It is common for patches generated by spatch that they include the SmPL
> which was used to generate the patch.
> See http://git.kernel.org/?p=linux%2Fkernel%2Fgit%2Ftorvalds%2Flinux-2.6.git&a=search&h=HEAD&st=commit&s=%3Csmpl%3E
> 
> But you can leave it out, if you wish.

I for one agree with David that this does not belong into the change
log.  Other maintainers just don't care or disagree.

If it is commonly seen, then only because Julia started it that way and
others blindly mimic her changelogs without giving it any thought, and
because many committers didn't edit or reject that for one reason or
another --- e.g. commit volume and work flow.

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.)

  - Reviewers and committers want to quickly see whether a submission
    is worthwhile and can work the way it is proposed.  (For them, a
    patch submission like this one is well described by the headline
    plus the hint that struct usb_driver.id_table is a const *.  BTW,
    the respective sentence in your changelog got the types wrong.)

The only people who may be interested in your find-and-replace macro are
those who write and use such macros themselves.  But for them, the more
appropriate source of information are the mailing lists and list
archives rather than the SCM's changelog.

The idea to note in the changelog with which editor or by which
find-and-replace macro a patch was generated is so way out there that it
is not even found as a negative example in "The Perfect Patch" section 4:
http://web.archive.org/web/20080722025711/http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt

End rant. :-)
-- 
Stefan Richter
-=====-==-=- ---= -==-=
http://arcgraph.de/sr/