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

[Eric Sunshine <sunshine@sunshineco.com>]

On Sun, May 3, 2015 at 4:13 PM, Fredrik Medley <fredrik.medley@gmail.com> wrote:
> 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.