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

From: Junio C Hamano <[email-masked]>
Date: Tue, 2 Jun 2026 23:43:04 +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 the
widest possible audience.

Helped-by: Patrick Steinhardt <[email-masked]>
Helped-by: Derrick Stolee <[email-masked]>
Signed-off-by: Junio C Hamano <[email-masked]>
---
 Documentation/SubmittingPatches | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index dec8aea4cb..df9f722bfe 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -472,6 +472,30 @@ 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.
+
+. 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.
+
+. 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-591-g9032776dcc