Ian Hilt <ian.hilt@xxxxxxxxx> writes:
> On Wed, 14 May 2008 at 11:46am -0700, Junio C Hamano wrote:
>
>> Ian Hilt <ian.hilt@xxxxxxxxx> 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@xxxxxxxxx>
Date: Wed May 14 14:30:55 2008 -0400
Documentation/git-describe.txt: make description more readable
Signed-off-by: Ian Hilt <ian.hilt@xxxxxxxxx>
Credit-to: Kevin Ballard <kevin@xxxxxx>
Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx>
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 ;-)
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
