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:36 UTC
Message-ID
<xmqqh5nlvzbk.fsf@gitster.g>
In-Reply-To
<ah7HZuy_WRCD9ZZ-@pks.im>
Patrick Steinhardt <ps@pks.im> writes:
Show 5 quoted lines
> On Tue, Jun 02, 2026 at 06:08:08PM +0900, Junio C Hamano wrote:
>> We talk about how a commit log message should look like, but do not
>> give advice on writing the cover letter to sell a series to widest
>
> s/to widest/to the widest/?
Thanks.
Show 23 quoted lines
>> +[[cover-letter]]
>> +=== Cover Letter
>> +
>> +The purpose of your cover letter is to sell your changes, explain what
>> +they are about, and get your target audience interested enough to read
>> +the patches.
>> +
>> +. Make sure your target audience can understand what the patches are
>> +  about and why they are needed without prior context.
>> +
>> +. 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.
>
> We might also recommend to include a range-diff in subsequent
> iterations. That being said though, I just sent a small series to the
> mailing list that recommends using b4, and there it get this for free.
> So no idea whether it's still worth it to then cover this here
> explicitly.

I think these are orthogonal. What b4 helps you with is the shape of the letter, how it looks like. This update is about the contents in the letter, what you convey to your readers.

Of course, "format-patch --cover-letter" also lets you do range-diff or interdiff, so they come for free. But the above description is not tied to any particular tool to prepare your cover letter.

Previous: Patrick SteinhardtNext: Derrick Stolee
Message 9 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.