From: Junio C Hamano Date: Tue, 02 Jun 2026 13:43:48 GMT Subject: Re: [PATCH 2/2] SubmittingPatches: describe cover letter Message-ID: In-Reply-To: Derrick Stolee writes: >> +. Make sure your target audience can understand what the patches are >> + about and why they are needed without prior context. > > The thing that I like to say about the cover letter is that this is > your opportunity to communicate why the value of your change is worth > the risk of regressions and the cost of maintenance. Perhaps: > > . Every code change comes with risk of regression and maintenance cost. > The cover letter should clearly communicate why the value of your > proposed change is worth applying. You can also describe how the risk > is reduced by the design choices you made while writing the patches. > > Or something similar may be helpful? I may just be over explaining. Yeah, it may be a bit on the heavy side, but complements what I wanted to achieve with this update very well. I wanted to encourage writing for wider audience, without leaving those "not in the know" behind. What you wrote above is more about what to write, which is very much appreciated. I think it fits well as the 0th item before the three-bullet list. >> +. For a second or subsequent iteration of the same topic, make sure >> + people who missed the earlier discussion can still understand what >> + the patches are about, so they can judge if the topic is worth their >> + time to read and comment on. >> + >> +. To help those who are familiar with earlier iterations, give a >> + summary of changes since the previous rounds. > > I find these updates to be particularly helpful, even for GitGitGadget > PRs that include a range-diff automatically. It's good to double-check > the human description of the update against the computed diff. Oh, absolutely. A GitGitGadget generated cover letter that lack any human input but just range-diff dump is often very hard to read, and the receiving end is better off pretending there was no useful information in the cover letter. "git diff @{-1}..." after applying the patches to the same base is sadly a lot easier to read than "git range-diff @{-1}..." for many series.