Subject: [PATCH 2/2] SubmittingPatches: describe cover letter

From: Junio C Hamano <[email-masked]>
Date: Tue, 2 Jun 2026 18:08:08 +0900

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 <[email-masked]>
---
 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