Re: [RFC 3/3] log: add an option to generate cover letter from a branch tip

Nicolas Morey-Chaisemartin <NMoreyChaisemartin@suse.de> writes:

This reminds me of a couple of random thoughts I had, so before I disconnect from my terminal and forget about them...

[1] format-patch and am must round-trip.

I mentioned four uses cases around the "cover letter at the tip" in my earlier message

    https://public-inbox.org/git/xmqqbmk68o9d.fsf@gitster.mtv.corp.google.com/

Specifically, (2) we should be able to run "format-patch" and record the log message of the empty commit at the tip to the cover letter, and (4) we should be able to accept such output with "am" and end up with the same sequence of commits as the original (modulo committer identity and timestamps). So from the output we produce with this step, "am" should be able to split the material that came from the original empty commit from the surrounding cruft like shortlog and diffstat. The output format of this step needs to be designed with that in mind.

[2] reusing cover letter material in merge may not be ideal.

When people write a cover letter, they write different things in it. What they wanted to achieve, why they chose the approach they took, how the series is organized, which part of the series they find iffy and/orneeds special attention from the reviewers, where to find the previous iteration, what changed since the previous iterations, etc.

All of them are to help the reviewers, many of who have already looked at the previous rounds, to understand and judge this round of the submission.

The message in a merge commit as a part of the final history, however, cannot refer to anything from "previous rounds", as the previous attempts are not part of the final history readers of "git log" can refer to whey they are trying to understand the merge. What exactly goes in a merge commit and how the messages are phrased may be different from project to project, but for this project, I've been trying to write them in an end-user facing terms, i.e. they are designed in such a way that "git log --first-parent --merges" can be read as if they were entries in the release notes, summarizing fixes and features by describing their user-visible effects. This is only one part of what people write in their cover letters (i.e. "what they wanted to achive").

So there probably needs a convention meant to be followed by human users when writing cover letters, so a mechanical process can tell which part of the text is to be made into the merge commit without understanding human languages.