Re: [PATCH] checkpatch: Warn on empty commit log bodies

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

Mark Brown wrote:
> On Sat, Feb 28, 2009 at 09:53:57PM -0500, Theodore Tso wrote:
>> Who's been complaining?  I can certainly tell you I'll complain in the
>> opposite direction, but that's because it actually causes me more work
> 
> Andrew Morton is one of them but not the only one.  Like I say, I don't
> want to claim that my changelogs are always ideal here, it was mostly
> the specific language used that made me think of doing this.

As far as I have observed, akpm's (Cc'd now) complaints are about
patches whose impact or benefit etc. are insufficiently explained ---
which is an issue on a higher level than pure formalism.  I believe I
too have seen the term "unchangelogged" (as you mentioned) in one of
those discussions but I associated lack of information with it rather
than a violation of a formalism.

I still say there are some straightforward changes which /can/ be well
explained in a single line (which would be the title line).  Still, by
far the most changes, including several kinds of janitorial changes,
require more explanation than that.  At which level a changelog should
start and how deep it should go is a rather subjective matter of course.
It is not trivial to give general advice on that, and it is impossible
to encode even simple tests for the quality of a changelog in a script
like checkpatch.

I for one am training how to write changelogs by the following methods:
 0. I occasionally write some of course.
 1. I intensively work with code written by other people long ago and
    wonder why it came to be how it is.  I look up when the code was
    added or changed and try to make sense of the changelogs which were
    provided at that time.
 2. I write release notes for a subsystem (targeted primarily towards
    users, secondarily towards developers) and use changelogs as primary
    input for that.
 3. I issue pull requests for new changes to be merged into the
    mainline.  These pull requests include a shortlog, plus extra
    information if the shortlog is unable to give a good picture of
    what the pull request is about.  The ideal would be that the
    shortlog says it all.
Nr. 1 especially trains to avoid lack of detail.  Nr. 2 and 3 train to
not forget the high-level viewpoint and to aim for clear language.  (I
am not sure about the success of this training though. ;-)
-- 
Stefan Richter
-=====-==--= --== ---=-
http://arcgraph.de/sr/