Re: [PATCH 2/2] SubmittingPatches: describe cover letter
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Jun 2, 2026, 13:43 UTC
- Message-ID
- <xmqqa4tdvyzv.fsf@gitster.g>
- In-Reply-To
- <fd588cff-be2b-4422-9c01-cef06b2ea5fd@gmail.com>
Derrick Stolee <stolee@gmail.com> writes:
Show 13 quoted lines
>> +. 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.
Show 11 quoted lines
>> +. 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.