Re: storing cover letter of a patch series?

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 6, 2016, 16:51 UTC
Message-ID: <xmqqziopj0x6.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <CAPc5daV51cwPs-8uc_SYLaod7RB7aDGYbjt-x-JsY1qNL81QRA@mail.gmail.com>

Junio C Hamano <gitster@pobox.com> writes:

Show 20 quoted lines

> On Fri, Aug 5, 2016 at 2:20 PM, Martin Fick <mfick@codeaurora.org> wrote:
>> On Friday, August 05, 2016 08:39:58 AM you wrote:
>>>  * A new topic, when you merge it to the "lit" branch, you
>>> describe the cover as the merge commit message.
>>>
>>>  * When you updated an existing topic, you tell a tool
>>> like "rebase -i -p" to recreate "lit" branch on top of
>>> the mainline.  This would give you an opportunity to
>>> update the cover.
>>
>> This is a neat idea.  How would this work if there is no
>> merge commit (mainline hasn't moved)?
>
> Sorry, I do not understand your question. You always
> merge into your own "lit", which is based on (some)
> version of the mainline. If a topic builds on top of the
> mainline, you "merge --no-ff" it into "lit". Because no
> merges on "lit" will be part of the future mainline anyway,
> even the project frowns upon a "no-ff" merge, that will
> not be a problem.

In any case, the "if you want to say more than what the individual commits say about the topic as a whole, say it in the merge that brings them all into an integration branch" is not just "a neat idea".

Recent versions of Git actively _encourages_ you to describe what it is about by opening your editor when you create a merge, and the cover letter material is something you would want the merge of your topic into the upstream to say when your topic finally lands there. And as the author of a topic, the person who writes the cover letter is well qualified to describe what the topic as a whole is about, how it relates to the state of the entire project before that merge happens. That is what you want to write in the cover letter.

So "write it in a merge log message yourself, and somehow find a way to propagate it to the maintainer's tree" is the natural consequence of thinking and working backwards from what we want to have in the final history; not any novel (or neat) idea.

What follows is that at the receiving end (i.e. "git am") it may be suboptimal to create an empty commit to record the cover letter material. Storing at the bottom of the received pile of commits is out of question. It _might_ be acceptable to queue it as the tip, and then teach "git merge $topic" to notice that $topic^0 is such a "cover letter commit", and turn itself into "git merge $topic^1 && git commit --amend -C $topic", though.