From: Junio C Hamano Date: Wed, 24 Jun 2026 20:21:10 +0000 (-0700) Subject: Merge branch 'kh/submittingpatches-trailers' into jch X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=94a7e416e3d9e2b91857f55824ff1a5b709bd237;p=thirdparty%2Fgit.git Merge branch 'kh/submittingpatches-trailers' into jch The trailer sections in SubmittingPatches have been updated to encourage use of standard trailers. * kh/submittingpatches-trailers: SubmittingPatches: note that trailer order matters SubmittingPatches: be consistent with trailer markup SubmittingPatches: document Based-on-patch-by trailer SubmittingPatches: discourage common Linux trailers SubmittingPatches: encourage trailer use for substantial help --- 94a7e416e3d9e2b91857f55824ff1a5b709bd237 diff --cc Documentation/SubmittingPatches index 2b51799f70,56706e55ea..5cdc4fef86 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@@ -469,33 -484,19 +485,43 @@@ While you can also create your own trai encourage you to instead use one of the common trailers in this project highlighted above. + Other projects might regularly refer to other kinds of data, like + `Fixes:` and `Link:` in the Linux Kernel project, but these ones in + particular are not used in this project. + 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". + `Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`. + + As mentioned under <> above, trailers are added in + chronological order; one person might sign-off on a patch and send it to + someone else, who then in turn adds her own sign-off. Further, any + trailers that you add beyond your sign-off should come before that + sign-off. That makes it clear what trailers which person added. +[[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)