git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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.

Previous: Derrick StoleeNext: Junio C Hamano
Message 11 of 16 in “Small updates to SubmittingPatches”
  1. 0/2 Small updates to SubmittingPatchesJunio C Hamano, Jun 2, 2026
  2. 1/2 SubmittingPatches: separate typofixes sectionJunio C Hamano, Jun 2, 2026
  3. Christian CouderJun 2, 2026
  4. Junio C HamanoJun 2, 2026
  5. Christian CouderJun 2, 2026
  6. Kristoffer HaugsbakkJun 2, 2026
  7. 2/2 SubmittingPatches: describe cover letterJunio C Hamano, Jun 2, 2026
  8. Patrick SteinhardtJun 2, 2026
  9. Junio C HamanoJun 2, 2026
  10. Derrick StoleeJun 2, 2026
  11. Junio C HamanoJun 2, 2026
  12. 0/2 Small updates to SubmittingPatchesJunio C Hamano, Jun 2, 2026
  13. 1/2 SubmittingPatches: separate typofixes sectionJunio C Hamano, Jun 2, 2026
  14. 2/2 SubmittingPatches: describe cover letterJunio C Hamano, Jun 2, 2026
  15. Derrick StoleeJun 2, 2026
  16. Patrick SteinhardtJun 4, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.