On Mon, Oct 30, 2017 at 11:29:37AM -0700, Stefan Beller wrote: > > I can live with fancily-formatted cover letters. BUT. I would say if > > your cover letter is getting quite long, you might consider whether some > > of its content ought to be going elsewhere (either into commit messages > > themselves, or into a design document or other place inside the repo). > > I am of the opinion that in an ideal workflow the cover letter would be > part of the merge commit message. It may even be editorialized or > annotated by the maintainer performing the merge, but not necessarily so. > > Currently I rarely pay attention to merges, because they are not exciting > (in a good way). I mostly know the texts that Junio puts into the merge > message[1] from the cooking email, and otherwise there is not much > information added there. Yes, I'd agree that for some topics it would be nice for the merge message to give any "big picture" details that wouldn't have made sense inside a single commit message. > However looking at *what* Junio puts there, is "why is this worthwhile > to merge from the *projects* point of view?", whereas the cover letter > most of the time talks about "Why the *contributor* wants this merged". > Often these are subtly different, so it would be nice to have these > two competing views around. Yes, there's really no reason we couldn't have both (e.g., Junio's maintainer synopsis followed by a marker, and then the original author's cover letter). The workflow within git is a little awkward, though. You'd want to pick up the cover letter information via "git am" when the branch is applied. But it doesn't go into a commit message until the merge. So where is it stored in the meantime? You'd need a branch->msg key/value store of some kind. Junio's workflow now actually uses the "pu" merges as the storage location while a topic is working its way up. But there's a period between "am" and running the integration cycle where it would need to go somewhere else. One other consideration is that the cover letter may get updated between rounds (e.g., because you changed patches in response to review, or even to discuss alternatives that came up and were rejected). That places a burden on the maintainer to update the prospective merge-message. So it may make more sense just to cross-reference those merges with the topics that spawned them on the mailing list. I.e., instead of copying the cover letter contents, just record the message-id (and update it whenever a new iteration of a topic is picked up via "git am"). That lets you get the cover letter information _and_ see any discussion or review around the patch. (But it has the same "where does this message-id go until the merge-commit is created" question). > > I actually have the opposite opinion. I find it annoying to have to wade > > through the same unchanged content for each round just to find the > > little snippet of "here's what's changed". > > Would you be happier if the "What changed?" goes first[2]? Yes, I think that would help. And marking the start of "old" information clearly so that the reader knows when they can stop looking. But then links do that pretty well, too (it's easy to choose whether to follow them or not). -Peff
