Subject: Re: [PATCH v4] Documentation fix: git log -p does not imply -c.

From: Adam Monsen <[email-masked]>
Date: Tue, 08 Mar 2011 12:46:33 -0800

Junio C Hamano wrote:
> Log messages should be sufficiently understandable offline without 
> having the web access.

Ok! Makes sense.

I read some stuff before writing it (like
Documentation/SubmittingPatches), but what I should have done is just
thumb through the log. Many commit messages are as you say they should be.

> Something like ...<snipped>... should be sufficient.

Thanks, I'll use that. It includes history and code details I didn't know.

This is good advice about how to fit in to the git community... would
you like a "commit message guide"? I did something like this for another
community (Mifos), and they found it helpful. Here's a rough draft:

-----------8<-----------

Commit message guide
====================

The suggested *format* of a commit message is covered in DISCUSSION in
git-commit(1). This guide covers philosophy of commit messages.

- Read previous commit messages. Emulate the best ones.
- Reveal your intentions.
- Answer questions you anticipate others will ask.
- Imagine you are reading this same commit message 10 years from now.
  What would be most helpful for you to quickly recall why these
  changes were made?
- Imagine someone else is reading this same commit message 10 years
  from now. What would be most helpful for them to quickly understand
  what this commit changes and why it was done?
- Commit messages should be sufficiently understandable without access
  to any online content.
- Be verbose!
- This is your chance to use time- and context-sensitive information
  relevant to code changed.
- Refer to related content.
  - other commits
  - mailing list discussions (but not in lieu of a proper description)

----------->8-----------

If you want a guide like this, some questions:
* do you want asciidoc, something else, or don't care?
* name it Documentation/CommitMessageGuide ? or something else?