Re: [PATCH 1/2] hw/vfio/migration: Remove unused 'exec/ram_addr.h' header

[Markus Armbruster <armbru@redhat.com>]

Alex Williamson <alex.williamson@redhat.com> writes:

> On Mon, 27 Feb 2023 16:24:16 +0000
> Alex Bennée <alex.bennee@linaro.org> wrote:
>
>> Alex Williamson <alex.williamson@redhat.com> writes:
>> 
>> > On Mon, 27 Feb 2023 11:32:57 +0100
>> > Philippe Mathieu-Daudé <philmd@linaro.org> wrote:
>> >  
>> >> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>  
>> >
>> > Empty commit logs are a pet peeve of mine, there must be some sort of
>> > motivation for the change, something that changed to make this
>> > possible, or perhaps why this was never necessary.  Thanks,  
>> 
>> I think that is a little unfair for this case as the motivation and
>> action are all covered by the summary line. Granted the overall goal is
>> covered by the cover letter and the following patch however for this
>> patch I would hope its self explanatory.
>
> The commit title only conveys that the include is unused and the action
> to therefore remove it.  The motivation is actually to create target
> independent objects and the specific reasoning here is that not only is
> this include file unnecessary, but forces per target builds.

I've been guilty of submitting patches with just a subject line, too.
E.g. commit 6f1e91f716a (error: Drop superfluous #include
"qapi/qmp/qerror.h"): I could have written that the header's contents
should go away, and the less we include it, the better.  I should have.

> This is exactly the "barrier to entry" I mention to Peter, it's obvious
> to the experts in the crowd, but it provides no underlying direction
> for those who might be more novice.  There is always some reasoning
> that can be included in a commit log beyond the simple "a therefore b"
> of the commit title.  Thanks,

Sometimes, the motivation is so obvious that omitting it for brevity's
sake feels harmless enough.  E.g. for commit 15b7646c7d0 (monitor: Drop
unnecessary includes) it's really just "include less to remake less".

Of course, when you explain motivation in the cover letter, it's almost
certainly best to explain it again in the commit messages.