Subject: Re: On-branch topic description support?

From: Junio C Hamano <[email-masked]>
Date: Wed, 20 Jul 2022 23:11:46 -0700

Elijah Newren <[email-masked]> writes:

> 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?

Yeah, I wanted to flesh out a bit more details on how this may work
before writing more about it, but what I envisioned would go
something along this line:

 * The authoring side would keep track of the description of the
   topic as a whole plus the description of inter-iteration changes,
   in the empty tip commit.  There may be some convention with a
   minimum mark-up (similar to how an innocuous three-dash line
   serves the "end of the message" marker in a patch e-mail) to
   separate the latter from the former.

 * "format-patch --cover-letter" would take the above, and add
   range-diff etc. that is easier to compute mechanically;

 * "am" may take the above, and keep the whole thing;

 * "merge" would keep the "main topic description" part and strip
   out everything after it, including the inter-iteration comparison
   and the range-diff, most likely by commenting the latter out when
   presenting it to the integrator.  So a lazy integrator can simply
   exit the editor to lose everything other than the topic
   description, and a more careful ones may refer to the supporting
   material to enhance/extend the topic description.