Re: [PATCH] Rephrased git-describe description

[Junio C Hamano <gitster@pobox.com>]

Ian Hilt <ian.hilt@gmail.com> writes:

> On Wed, 14 May 2008 at 11:46am -0700, Junio C Hamano wrote:
>
>> Ian Hilt <ian.hilt@gmail.com> writes:
>>
>>> git-describe: Make description more readable.
>>
>> Thanks, both.  I think the above is meant to be on the Subject: line, and
>> the text certainly is more readable.
>
> This is probably a stupid question, but is that all you want for
> a commit message?

I think the following is clear enough to describe what your patch did.

    commit b7893cde53eb2834deb16820eccb709d2636b81b
    Author: Ian Hilt <ian.hilt@gmail.com>
    Date:   Wed May 14 14:30:55 2008 -0400

        Documentation/git-describe.txt: make description more readable

        Signed-off-by: Ian Hilt <ian.hilt@gmail.com>
        Credit-to: Kevin Ballard <kevin@sb.org>
        Signed-off-by: Junio C Hamano <gitster@pobox.com>

When made into a line in the shortlog, this makes it clear that it affects
the documentation (and documentation only), and it describes what the
patch did.

If there is a guiding principle that drove the change the patch did, and
that guiding principle is something other people can follow when fixing
similar breakages, it often is a good idea to describe what they are in
the body of the commit log message.  But I did not see such a clear,
reusable guiding principle for this change.

What I mean by a guiding principle in this case is something like...

 - command description should start with a clear description of what it
   does, so that the readers can decide if that is the command they want
   to solve their problem with by reading the very first part;

 - and then it should describe how it does it in an unambiguous and easy
   to read language.

Then you can have a comparison between the text before and after the
change to explain why the updated text is more unambiguous.  But you would
risk ending up with a textbook of English composition which is not what we
necessarily want to do here ;-)