SubmittingPatches: describe cover letter
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 <ps@pks.im> Helped-by: Derrick Stolee <stolee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Jun 2, 2026 at 23:43 UTC
bc58f1c7347a38175782b5a745443f109773a501
1 file changed
+24
Documentation/SubmittingPatches
+24
@@ -472,6 +472,30 @@ highlighted above.
472
Only capitalize the very first letter of the trailer, i.e. favor
473
"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
474
475
+[[cover-letter]]
476
+=== Cover Letter
477
+
478
+The purpose of your cover letter is to sell your changes, explain what
479
+they are about, and get your target audience interested enough to read
480
+the patches.
481
+
482
+. Every code change comes with risk of regression and maintenance cost.
483
+ The cover letter should clearly communicate why the value of your
484
+ proposed change is worth applying. You can also describe how the risk
485
+ is reduced by the design choices you made while writing the patches.
486
+
487
+. Make sure your target audience can understand what the patches are
488
+ about and why they are needed without prior context.
489
+
490
+. For a second or subsequent iteration of the same topic, make sure
491
+ people who missed the earlier discussion can still understand what
492
+ the patches are about, so they can judge if the topic is worth their
493
+ time to read and comment on.
494
+
495
+. To help those who are familiar with earlier iterations, give a
496
+ summary of changes since the previous rounds.
497
+
498
+
499
[[ai]]
500
=== Use of Artificial Intelligence (AI)
501