Re: [PATCH] Rephrased git-describe description

From: Junio C Hamano <gitster@pobox.com>
Date: May 17, 2008, 00:03 UTC
Message-ID: <7vej81er0r.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <alpine.LNX.1.10.0805141856380.30187@sys-0.hiltweb.site>

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

Show 11 quoted lines

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