Re: On-branch topic description support?

> On Wed, Jul 20, 2022 at 5:08 PM Junio C Hamano <gitster@pobox.com> wrote:
>> I've been playing with this idea from time to time, but recently I
>> started seeing a related discussion on the b4 front, so I thought I
>> would throw it out and how people would think.
>>
>> We made "git merge" not to silently commit the result, but open the
>> editor to encourage the integrator to describe what the topic is
>> about.  We also made "git format-patch" prepare [PATCH 0/n] aka
>> "cover letter" so that the author of the patch series can express
>> what the overall topic is about.  What the author should say in the
>> cover letter very much overlaps what the integrator wants to have in
>> the log message of the commit that merges the topic to the
>> integration branch.
>>
>> But there are two (and half) links from format-patch to that merge
>> commit that are missing.
>>
>>  - You cannot prepare the cover letter material while working on the
>>    topic---instead, you have to write one by editing the output from
>>    "format-patch --cover-letter";
>>
>>  - "git am" at the receiving end discards the cover letter when
>>    queuing the e-mailed patches to a topic.
>>
>>  - "git merge" cannot take advantage of the cover letter that was
>>    discarded when the topic was queued.
>>
>> So, here is how I would imagine a slightly better world may work.
>>
>>  * When you are almost finished with the initial draft of your
>>    topic, you'd write a cover letter, and record it as the log
>>    message of an empty commit at the tip of the topic.  

>> As you go on
>>    polishing the topic with "rebase -i", the empty commit would be
>>    kept (if we currently lose an empty commit by default, we may
>>    need to teach "rebase -i" to special case an empty commit at the
>>    tip of the range to make this convenient to use), and you would
>>    keep it up to date as you update the topic.
> No need for rebase changes here.  By default, it preserves commits
> which start empty, and only drops commits which *become* empty.
>
> (If one wants to drop commits that start empty, you can pass
> `--no-keep-empty`.  If you want to keep commits that become empty, you
> can use either `--empty=keep` or `--empty=ask`.)
>
>>  * "git format-patch" would notice that the topic has such an empty
>>    commit at the tip, and use the log message from it to
>>    pre-populate the cover letter.
>>
>>  * "git am" would learn an option to save the cover letter [0/n] and
>>    create such an empty commit at the tip of the branch.
>>
>>  * "git merge" would learn an option to recognize that the branch
>>    being merged has such an empty commit at the tip, and instead
>>    merge the parent of the tip of the branch into the integration
>>    branch, while using the log message of the discarded tip commit
>>    in the log message of the merge itself.
>>
>> Yes, there is "git config branch.mytopic.description" that helps
>> when pre-populating the cover letter, but that only helps at the
>> origin, and it is not shared between your personal repositories.
>> If you have the draft of the cover letter as part of the branch,
>> you can push/fetch them around just like all the "real" commits
>> you are working on.
>>
>> Regardless of where the cover letter comes from, the changes to "am"
>> and "merge" dreamed above in this message would be useful, and that
>> is the primary reason why I am envisioning that right at the origin
>> having the topic description as an empty commit at the tip would be
>> the most convenient.  It would match the shape of the history at the
>> author side and at the side who runs "git am".
> Seems mostly reasonable, but I'm curious about one thing:
>
> The cover letter material often includes stuff that would not make
> sense for the merge message (e.g. "Rebased this version on master
> because of conflicts with ...", "Changes since v3", "I'm a little
> unsure of the logic in Patch 5", "Patch 3 might be controversial; take
> a look", etc.)  Would there be some kind of syntax for specifying the
> part of the cover letter meant to be used in the merge commit message,
> or would we just start out with it pre-populating the commit message
> and expect the integrator to cull out the irrelevant parts?