Re: [PATCH] upload-pack: Optionally allow fetching reachable sha1

From: Eric Sunshine <sunshine@sunshineco.com>
Date: May 3, 2015, 21:35 UTC
Message-ID: <CAPig+cShtk7Be_miSfgzXTPdWxfYmFjJ+kEg5xr+2yLyEhfLvQ@mail.gmail.com>
In-Reply-To: <CABA5-znFVPunBxET-42jDTC00gH8VMkG280Ptyr8FUU6vfuiCA@mail.gmail.com>

On Sun, May 3, 2015 at 4:13 PM, Fredrik Medley <fredrik.medley@gmail.com> wrote:

Show 16 quoted lines

> 2015-05-03 19:40 GMT+02:00 Junio C Hamano <gitster@pobox.com>:
>> Fredrik Medley <fredrik.medley@gmail.com> writes:
>>> For you who don't remember the email discussion, look through the references.
>>
>> Please don't do this.  Always describe the background yourself in
>> the log message so that "git log" can be read offline.  "describe
>> yourself" can be done by summarizing earlier discussion, borrowing
>> others' words, of course.  And it is a very good idea to give
>> references like you did after your summary to optionally allow
>> people to verify your summary is correct.
>
> Okay, I understand. My intention was to recapture the old thread, but
> to keep the part under the references for the commit message. When
> I get this answer, I do see that this is impossible to understand and I
> should probably have added a cover-letter instead. (This is my first
> time every I've supplied patches to such an open-source project.)

Welcome to open-source and to git.

> Is the text under the reference enough describing or should there
> be added some more background text?
> Unless someone asks for more answers about my attempt to recap
> the old mail thread, I skip commenting on this part.

What Junio meant was that the commit message should be sufficiently self-contained such that someone reading it should be able to understand the problem you're solving without being familiar with past discussions (and without having to chase down links), and why the solution you've chosen is desirable.

In this case, the paragraph following the references in your patch, which you had intended as the full commit message, may not be sufficient. You might come closer to a good commit message by fleshing out the paragraph preceding the references, and following that by the paragraph after the references. By "fleshing out", I mean providing salient information from the cited discussions at the points where you referenced them via [n] notation.

Your commit message should explain the problem in the current implementation (possibly justifying why you consider it a problem), and an explanation of the solution. You will want to keep the references (but move them to the bottom of the commit message), and cite them when appropriate in your explanation.

For a single patch like this, you don't really need a cover letter. Just make sure the commit message provides sufficient explanation and is self-contained. If you want to provide extra commentary not intended for the commit message, place it below the "---" line after your sign-off and before the diffstat.