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

[PATCH 2/2] SubmittingPatches: describe cover letter

From
Junio C Hamano <gitster@pobox.com>
Date
Jun 2, 2026, 09:08 UTC
Message-ID
<20260602090808.87837-3-gitster@pobox.com>
In-Reply-To
<20260602090808.87837-1-gitster@pobox.com>

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 possible audience.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index dec8aea4cb..8ff1792b9b 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -472,6 +472,25 @@ highlighted above.
 Only capitalize the very first letter of the trailer, i.e. favor
 "Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
 
+[[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.
+
+
 [[ai]]
 === Use of Artificial Intelligence (AI)
 
-- 
2.54.0-567-gf25c749695
Previous: Kristoffer HaugsbakkNext: Patrick Steinhardt
Message 7 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.