Re: [PATCH v5 04/20] scripts/clean-includes: Improve --git commit message

[Markus Armbruster]

Juan Quintela <quintela@redhat.com> writes:

> Markus Armbruster <armbru@redhat.com> wrote:
>> Juan Quintela <quintela@redhat.com> writes:
>>
>>> Markus Armbruster <armbru@redhat.com> wrote:
>>>> Juan Quintela <quintela@redhat.com> writes:
>>>>
>>>>> Markus Armbruster <armbru@redhat.com> wrote:
>>>>>> The script drops #include "qemu/osdep.h" from headers.  Mention it in
>>>>>> the commit message it uses for --git.
>>>>>>
>>>>>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>>>>>> ---
>>>>>>  scripts/clean-includes | 4 ++--
>>>>>>  1 file changed, 2 insertions(+), 2 deletions(-)
>>>>>>
>>>>>> diff --git a/scripts/clean-includes b/scripts/clean-includes
>>>>>> index f0466a6262..f9722c3aec 100755
>>>>>> --- a/scripts/clean-includes
>>>>>> +++ b/scripts/clean-includes
>>>>>> @@ -193,8 +193,8 @@ if [ "$GIT" = "yes" ]; then
>>>>>>      git commit --signoff -F - <<EOF
>>>>>>  $GITSUBJ: Clean up includes
>>>>>>  
>>>>>> -Clean up includes so that osdep.h is included first and headers
>>>>>> -which it implies are not included manually.
>>>>>> +Clean up includes so that qemu/osdep.h is included first in .c, and
>>>>>> +not in .h, and headers which it implies are not included manually.
>>>>>
>>>>> I give a tree.
>>>>>
>>>>> Clean up includes so qemu/osdep.h is never used in .h files.  It makes
>>>>> sure that qemu/osdep.h is only used in .c files.  Once there, it assures
>>>>> that .h files already included in qemu/osdep.h are not included a second
>>>>> time on the .c file.
>>>>>
>>>>> What do you think?
>>>>
>>>> Neglects to mention qemu/osdep.h goes first in .c.
>>>
>>> /me tries again
>>>
>>> What about:
>>>
>>> The file qemu/osdep.h should only be included in .c files.  And it has
>>> to be the first included file.
>>
>> Suggest "has to be included first."
>
> Ok to this change.
>
>>
>>> This script does several things:
>>> - Remove qemu/osdep.h from .h files.
>>
>> Correct.  Could say "inclusion of qemu/osdep.h"
>
> I try to minimize whatever word that "includes" "includ*" (pun intended).
>
>>> - If qemu/osdep.h is included in a .c file it is moved to the first
>>>   included position if it is anywhere else.
>>
>> Not quite.  The script ensures all the .c include it, and include it
>> first.
>
> Oh, then it is easier.
>
> - It ensures that qemu/osdep.h is the first included file in all .c files.
>
>>> - Remove from .h files all include files that are already present in
>>>   qemu/osdep.h.
>>
>> They're removed from .h, too.
>
> Ah, didn't know this bit.
>
>> Sure you want to continue wordsmithing?  ;)
>
> Yeap, I *hate* error messages that I can't parse (or have to read it ten
> times before I understand them).
>
> So, we end with:
>
> The file qemu/osdep.h should only be included in .c files.  And it has
> to be included first.
>
> This script does three things:
> - Remove qemu/osdep.h from .h files.
> - It ensures that qemu/osdep.h is the first included file in all .c files.
> - Include files contained in qemu/osdep.h are removed form all .c and .h
>   files.
>
> Is this better?

It's less terse.  Fine with me.  The mix of passive and active voice
feels a bit awkward, though.  Another try:

  All .c should include qemu/osdep.h first.  This script performs three
  related cleanups:

  * Ensure .c files include qemu/osdep.h first.
  * Including it in a .h is redundant, since the .c  already includes
    it.  Drop such inclusions.
  * Likewise, including headers qemu/osdep.h includes is redundant.
    Drop these, too.