[PATCH v2 2/2] SubmittingPatches: describe cover letter
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Jun 2, 2026, 14:43 UTC
- Message-ID
- <20260602144304.3341000-3-gitster@pobox.com>
- In-Reply-To
- <20260602144304.3341000-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 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> --- 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