From: kristofferhaugsbakk@fastmail.com Date: Wed, 17 Jun 2026 20:52:14 GMT Subject: [PATCH v2 0/5] SubmittingPatches: update and flesh out trailer sections Message-ID: In-Reply-To: From: Kristoffer Haugsbakk Topic name (applied) kh/submittingpatches-trailers Topic summary: Flesh out and update the trailer sections. All of these points have come up on the mailing list. At least for me. And `Based-on-patch-by` is a nice-to-have documented kind of thing. [elide “since January” from v1...] Link to v1: https://lore.kernel.org/git/CV_SubPatches_trailers.8f3@msgid.xyz/ § Changes in v2 See the patch Notes for details. • Improve commit messages • Drop patch “discuss non-ident trailers” • https://lore.kernel.org/git/CV_SubPatches_trailers.8f3@msgid.xyz/T/#m53305dbb8c1f19b06be781ee720fc3be875a326d • Rewrite “note that trailer order matters” to emphasize chronological order and to also mention it in the DCO section • See https://lore.kernel.org/git/xmqq8q8mt4eo.fsf@gitster.g/ [1/5] SubmittingPatches: encourage trailer use for substantial help [2/5] SubmittingPatches: discourage common Linux trailers [3/5] SubmittingPatches: document Based-on-patch-by trailer [4/5] SubmittingPatches: be consistent with trailer markup [5/5] SubmittingPatches: note that trailer order matters Documentation/SubmittingPatches | 46 ++++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 10 deletions(-) Interdiff against v1: diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 89542263444..dceeb5a1817 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -427,6 +427,10 @@ D-C-O. Indeed you are encouraged to do so. Do not forget to place an in-body "From: " line at the beginning to properly attribute the change to its true author (see (2) above). +Place this `Signed-off-by:` trailer at the end, after trailers added by +others and after other trailers added by you; see +<> below ("chronological order"). + This procedure originally came from the Linux kernel project, so our rule is quite similar to theirs, but what exactly it means to sign-off your patch differs from project to project, so it may be different @@ -467,8 +471,8 @@ These are the common trailers in use: of a patch before submitting it. . `Based-on-patch-by:` is used when someone else authored parts of the patch that you are submitting. This might be relevant if someone sent - a patch to the mailing list without a commit message or a - `Signed-off-by:` and you have picked it up. + a patch to the mailing list with their sign-off. (Be mindful and ask + them to sign off on it if they did not.) . `Helped-by:` is used to credit someone who suggested ideas for changes without providing the precise changes in patch form. . `Mentored-by:` is used to credit someone with helping develop a @@ -478,10 +482,7 @@ These are the common trailers in use: While you can also create your own trailer if the situation warrants it, we encourage you to instead use one of the common trailers in this project -highlighted above. A trailer that credits someone might be more likely -to be accepted since these are the most common ones. But another kind of -trailer might be relevant, for example to link to an issue tracker -belonging to a downstream project that is affected by a bug in Git. +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 @@ -490,10 +491,11 @@ 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:`. -Note that these trailers should come before your `Signed-off-by:` -trailer. You are signing off to the patch as well as the message. This -also makes it clear who added trailers when multiple people have signed -off on a patch. +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. [[ai]] === Use of Artificial Intelligence (AI) Range-diff against v1: 1: 366c0f43b71 ! 1: 835eb736f39 SubmittingPatches: encourage trailer use for substantial help @@ Commit message contribution”.[2] Adding trailers is already encouraged, but in the section `send-patches`. - Let’s replace “If you like” with outright encouragment in this section + Let’s replace “If you like” with outright encouragement in this section so that all trailer discussion (except s-o-b; see `sign-off` section) is contained in this section; a link to from `send-patches` makes this information equally visible. @@ Commit message Now we need to make a heading for `commit-trailers` in order for the HTML output to make sense. - At the same, it is important to temper this recommendation to a sign- - ificant enough contribution; in my experience beginners can be eager + At the same time, it is important to temper this recommendation to a + significant enough contribution; in my experience beginners can be eager to add a trailer for everyone who replies with an action point that is followed up on. 2: c78fb49c245 < -: ----------- SubmittingPatches: discuss non-ident trailers 3: cff069ced4e ! 2: 5a652b8e14d SubmittingPatches: discourage common Linux trailers @@ Commit message git.git `master` from time to time. This project does regularly mention what commits a patch/commit fixes, - but that is done inline in the commit message proper (c.f. the trailer + but that is done inline in the commit message proper (cf. the trailer block of the message). For `Link`: These are used both to link back to the patch submission as @@ Commit message Signed-off-by: Kristoffer Haugsbakk ## Documentation/SubmittingPatches ## -@@ Documentation/SubmittingPatches: to be accepted since these are the most common ones. But another kind of - trailer might be relevant, for example to link to an issue tracker - belonging to a downstream project that is affected by a bug in Git. +@@ Documentation/SubmittingPatches: While you can also create your own trailer if the situation warrants it, we + 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 4: 278eb2c5d21 ! 3: 5e53999b2e9 SubmittingPatches: document Based-on-patch-by trailer @@ Documentation/SubmittingPatches: These are the common trailers in use: of a patch before submitting it. +. `Based-on-patch-by:` is used when someone else authored parts of the + patch that you are submitting. This might be relevant if someone sent -+ a patch to the mailing list without a commit message or a -+ `Signed-off-by:` and you have picked it up. ++ a patch to the mailing list with their sign-off. (Be mindful and ask ++ them to sign off on it if they did not.) . `Helped-by:` is used to credit someone who suggested ideas for changes without providing the precise changes in patch form. . `Mentored-by:` is used to credit someone with helping develop a 5: 347c72e4e08 = 4: dd47fabe917 SubmittingPatches: be consistent with trailer markup 6: 1c7e9ad8e69 ! 5: 20f04e18cee SubmittingPatches: note that trailer order matters @@ Metadata ## Commit message ## SubmittingPatches: note that trailer order matters - It matters where you put the s-o-b; it should be last. You are signing - off on the patch as well as the whole message up to that point. + It matters where you put new trailers: they should be added in + chronological order, and each person who passes on a patch should add + their s-o-b last. You are signing off on the patch as well as the whole + message up to that point. This also makes it clear who added what: @@ Commit message Acked-by: The (Late) Reviewer Signed-off-by: The Maintainer - The the first ack was added by the contributor and the second one was - added by the maintainer. + The first ack was added by the contributor and the second one was added + by the maintainer. + Helped-by: Junio C Hamano Signed-off-by: Kristoffer Haugsbakk ## Documentation/SubmittingPatches ## +@@ Documentation/SubmittingPatches: D-C-O. Indeed you are encouraged to do so. Do not forget to + place an in-body "From: " line at the beginning to properly attribute + the change to its true author (see (2) above). + ++Place this `Signed-off-by:` trailer at the end, after trailers added by ++others and after other trailers added by you; see ++<> below ("chronological order"). ++ + This procedure originally came from the Linux kernel project, so our + rule is quite similar to theirs, but what exactly it means to sign-off + your patch differs from project to project, so it may be different @@ Documentation/SubmittingPatches: 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:`. -+Note that these trailers should come before your `Signed-off-by:` -+trailer. You are signing off to the patch as well as the message. This -+also makes it clear who added trailers when multiple people have signed -+off on a patch. ++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. + [[ai]] === Use of Artificial Intelligence (AI) base-commit: 1ff279f3404a482a83fb04c7457e41ab26884aea -- 2.54.0.22.g9e26862b904