From 66ebad2775a1e3904f724522519a7290cb8d9709 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 2 Jun 2026 23:43:03 +0900 Subject: [PATCH 1/2] SubmittingPatches: separate typofixes section The existing text said something about tests (with [[tests]] to make it easier to refer to it from elsewhere) and then flowed into a different topic of typofixes, but it was unclear where the latter started. Add a similar [[typofixes]] marker to the document. Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d570184ec8..dec8aea4cb 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -237,6 +237,7 @@ Do not forget to update the documentation to describe the updated behavior and make sure that the resulting documentation set formats well (try the Documentation/doc-diff script). +[[typofixes]] We currently have a liberal mixture of US and UK English norms for spelling and grammar, which is somewhat unfortunate. A huge patch that touches the files all over the place only to correct the inconsistency From bc58f1c7347a38175782b5a745443f109773a501 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 2 Jun 2026 23:43:04 +0900 Subject: [PATCH 2/2] 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 Helped-by: Derrick Stolee Signed-off-by: Junio C Hamano --- 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)