{"thread":{"id":"65789","subject":"[PATCH 0/6] SubmittingPatches: update and flesh out trailer sections","startedAt":"2026-06-10T22:23:16Z","lastAt":"2026-06-19T05:47:11Z","messageCount":32,"participants":["kristofferhaugsbakk@fastmail.com","Junio C Hamano","Patrick Steinhardt","Kristoffer Haugsbakk"],"isPatch":true,"patchVersion":1,"patchTotal":6},"messages":[{"id":"545208","messageId":"CV_SubPatches_trailers.8f3@msgid.xyz","threadId":"65789","inReplyTo":null,"subject":"[PATCH 0/6] SubmittingPatches: update and flesh out trailer sections","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T22:22:43Z","receivedAt":"2026-06-10T22:23:16Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name: kh/submitting-patches-trailers\n\nTopic summary: Flesh out and update the trailer sections.\n\nAll of these points have come up on the mailing list. At least for me.\nAnd `Based-on-patch-by` is a nice-to-have documented kind of thing.\n\nI have had these lying around since January since I got distracted. I just\nwrote this cover letter today. But I think this still makes sense.\n\n[1/6] SubmittingPatches: encourage trailer use for substantial help\n[2/6] SubmittingPatches: discuss non-ident trailers\n[3/6] SubmittingPatches: discourage common Linux trailers\n[4/6] SubmittingPatches: document Based-on-patch-by trailer\n[5/6] SubmittingPatches: be consistent with trailer markup\n[6/6] SubmittingPatches: note that trailer order matters\n\n Documentation/SubmittingPatches | 46 +++++++++++++++++++++++++--------\n 1 file changed, 35 insertions(+), 11 deletions(-)\n\n\nbase-commit: 1ff279f3404a482a83fb04c7457e41ab26884aea\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545209","messageId":"encourage_substantial.8f4@msgid.xyz","threadId":"65789","inReplyTo":"CV_SubPatches_trailers.8f3@msgid.xyz","subject":"[PATCH 1/6] SubmittingPatches: encourage trailer use for substantial help","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T22:22:44Z","receivedAt":"2026-06-10T22:23:33Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTrailers beyond the mandatory s-o-b are regularly used based on my\nlast two years of reading the mailing list. Moreover, reviewers might\nencourage it.[1]\n\nThis is also in line with the project crediting both commit authors and\npeople mentioned in trailers each release; “Nobody is THE one making\ncontribution”.[2]\n\nAdding trailers is already encouraged, but in the section `send-patches`.\nLet’s replace “If you like” with outright encouragment in this section\nso that all trailer discussion (except s-o-b; see `sign-off` section) is\ncontained in this section; a link to from `send-patches` makes this\ninformation equally visible.\n\nNow we need to make a heading for `commit-trailers` in order for the\nHTML output to make sense.\n\nAt the same, it is important to temper this recommendation to a sign-\nificant enough contribution; in my experience beginners can be eager\nto add a trailer for everyone who replies with an action point that is\nfollowed up on.\n\nLet’s also spell out that these trailers should follow the Git author/\ncommitter format. One might naturally just write the name, but in that\ncase it will not be picked up by:\n\n git shortlog --group=trailer:\n\nand normalization via `.mailmap` will not work.\n\nAlso introduce the list of common trailers as such. Granted, this is\nalready implied by the later paragraph about “create your own trailer”,\nso this just frontloads this information.\n\n† 1: https://lore.kernel.org/git/CAP8UFD0POvYDgGtEx8GBhvKkd8XzzWQsy8XxAKL9M3+uz3ka+w@mail.gmail.com/#:~:text=for%20at%20least\n† 2: https://lore.kernel.org/git/xmqqzh248sy0.fsf@gitster.c.googlers.com/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/SubmittingPatches | 14 +++++++++++---\n 1 file changed, 11 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 176567738d4..0b12badf86d 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -443,8 +443,16 @@ identifying, and not misleading.\n The goal of this policy is to allow us to have sufficient information to contact\n you if questions arise about your contribution.\n \n+=== Commit trailers\n [[commit-trailers]]\n-If you like, you can put extra trailers at the end:\n+It is polite to credit people who have helped with your work to a\n+substantial enough degree. This project uses commit trailers for that,\n+where the credited person is written out like a Git author, i.e. with\n+both their name and their email address. Note that the threshold to\n+credit someone is a judgement call, and crediting someone for simple\n+review work is certainly not necessary.\n+\n+These are the common trailers in use:\n \n . `Reported-by:` is used to credit someone who found the bug that\n the patch attempts to fix.\n@@ -562,8 +570,8 @@ when the maintainer did not heavily participate in the discussion and\n instead left the review to trusted others.\n \n Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and\n-`Tested-by:` lines as necessary to credit people who helped your\n-patch, and \"cc:\" them when sending such a final version for inclusion.\n+`Tested-by:` (see <>), and \"cc:\" them\n+when sending such a final version for inclusion.\n \n ==== `format-patch` and `send-email`\n \n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545210","messageId":"non-ident_trailers.8f5@msgid.xyz","threadId":"65789","inReplyTo":"CV_SubPatches_trailers.8f3@msgid.xyz","subject":"[PATCH 2/6] SubmittingPatches: discuss non-ident trailers","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T22:22:45Z","receivedAt":"2026-06-10T22:23:52Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nBriefly discuss trailers that do not credit people. This continues the\ndiscussion from the previous commit about using trailers for *people*.\n\nUsing non-ident trailers can be relevant. The contributor should just be\nencouraged to consider whether it is useful or not.\n\nThe larger trend here is to discourage using trailers as a dumping\nground for any kind of metadata in the spirit of “it doesn’t hurt”.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/SubmittingPatches | 5 ++++-\n 1 file changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 0b12badf86d..51c308a89a8 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -474,7 +474,10 @@ These are the common trailers in use:\n \n While you can also create your own trailer if the situation warrants it, we\n encourage you to instead use one of the common trailers in this project\n-highlighted above.\n+highlighted above. A trailer that credits someone might be more likely\n+to be accepted since these are the most common ones. But another kind of\n+trailer might be relevant, for example to link to an issue tracker\n+belonging to a downstream project that is affected by a bug in Git.\n \n Only capitalize the very first letter of the trailer, i.e. favor\n \"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545212","messageId":"discourage_Linux.8f6@msgid.xyz","threadId":"65789","inReplyTo":"CV_SubPatches_trailers.8f3@msgid.xyz","subject":"[PATCH 3/6] SubmittingPatches: discourage common Linux trailers","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T22:22:46Z","receivedAt":"2026-06-10T22:24:10Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThe Linux Kernel regularly uses trailers (or “tags”) `Fixes` and\n`Link`. Sometimes people submit patches to this project with them.\nThey have their use in that project but it is not clear what purpose\nthey would serve here.\n\nFor `Fixes`: Linux has many trees, and applying patches with\ncherry-picks is common. A `Fixes` trailer in commit C2 pointing to\ncommit C1 helps the cherry-picker figure out that she probably needs\nC2 if she wants to apply C1. See linux/d5d6281a (checkpatch: check for\nmissing Fixes tags, 2024-06-11):[1]\n\n Why are stable patches encouraged to have a fixes tag? Some people\n mark their stable patches as \"# 5.10\" etc. This is useful but a\n Fixes tag is still a good idea. For example, the Fixes tag helps in\n review. It helps people to not cherry-pick buggy patches without\n also cherry-picking the fix.\n\nIn contrast the Git project has few trees (to my knowledge), and there\nis much less need to cherry-pick fixes as opposed to either using\nbackmerges or rebasing all of the downstream tree’s commits on top of\ngit.git `master` from time to time.\n\nThis project does regularly mention what commits a patch/commit fixes,\nbut that is done inline in the commit message proper (c.f. the trailer\nblock of the message).\n\nFor `Link`: These are used both to link back to the patch submission as\nwell as with footnotes. In contrast this project has `refs/notes/amlog`\nfor linking back to the patch submissions, and footnotes are only used\nin the commit message proper.\n\n† 1: Commit linux/d5d6281a has “linux” in front of it since this commit\n is from the Linux Kernel, not Git. Example of a Linux tree—as well\n as an example of `Link`—is [2].\n\nLink: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/ [2]\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/SubmittingPatches | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 51c308a89a8..5dc32128883 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -479,6 +479,10 @@ to be accepted since these are the most common ones. But another kind of\n trailer might be relevant, for example to link to an issue tracker\n belonging to a downstream project that is affected by a bug in Git.\n \n+Other projects might regularly refer to other kinds of data, like\n+`Fixes:` and `Link:` in the Linux Kernel project, but these ones in\n+particular are not used in this project.\n+\n Only capitalize the very first letter of the trailer, i.e. favor\n \"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n \n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545213","messageId":"Based-on-patch-by.8f7@msgid.xyz","threadId":"65789","inReplyTo":"CV_SubPatches_trailers.8f3@msgid.xyz","subject":"[PATCH 4/6] SubmittingPatches: document Based-on-patch-by trailer","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T22:22:47Z","receivedAt":"2026-06-10T22:24:28Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis trailer comes up often enough and the use case is not fully covered\nby the other trailers here. For example, it is sometimes better to use\nthis trailer instead of `Co-authored-by:`.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n Note: “*can be* used”. Not “is”. Based on practical usage, I think\n it would be wrong to claim that someone sending a literal patch\n snippet via email means that this is the tag that you ought to\n use. I think e.g. `Helped-by` might be used instead.\n \n I also think that the “is” for `Helped-by` is too strongly worded\n for the same reasons.\n\n Documentation/SubmittingPatches | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 5dc32128883..c1d12e38b28 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -465,6 +465,10 @@ These are the common trailers in use:\n and found it to have the desired effect.\n . `Co-authored-by:` is used to indicate that people exchanged drafts\n of a patch before submitting it.\n+. `Based-on-patch-by:` can be used when someone else authored parts of\n+ the patch that you are submitting. This might be relevant if someone\n+ sent a patch to the mailing list without a commit message or a\n+ `Signed-off-by:` and you have picked it up.\n . `Helped-by:` is used to credit someone who suggested ideas for\n changes without providing the precise changes in patch form.\n . `Mentored-by:` is used to credit someone with helping develop a\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545214","messageId":"just_trailer_markup.8f8@msgid.xyz","threadId":"65789","inReplyTo":"CV_SubPatches_trailers.8f3@msgid.xyz","subject":"[PATCH 5/6] SubmittingPatches: be consistent with trailer markup","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T22:22:48Z","receivedAt":"2026-06-10T22:24:47Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThe rest of this section and (most importantly) the list has decided to\nuse `:`. So let’s use backticks (`) and a colon (:) throughout the\ndocument.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/SubmittingPatches | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex c1d12e38b28..3d2e9ecfbb8 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -374,7 +374,7 @@ or, on an older version of Git without support for --pretty=reference:\n ....\n \n [[sign-off]]\n-=== Certify your work by adding your `Signed-off-by` trailer\n+=== Certify your work by adding your `Signed-off-by:` trailer\n \n To improve tracking of who did what, we ask you to certify that you\n wrote the patch or have the right to pass it on under the same license\n@@ -411,7 +411,7 @@ d. I understand and agree that this project and the contribution\n this project or the open source license(s) involved.\n ____\n \n-you add a \"Signed-off-by\" trailer to your commit, that looks like\n+you add a `Signed-off-by:` trailer to your commit, that looks like\n this:\n \n ....\n@@ -421,7 +421,7 @@ this:\n This line can be added by Git if you run the git-commit command with\n the -s option.\n \n-Notice that you can place your own `Signed-off-by` trailer when\n+Notice that you can place your own `Signed-off-by:` trailer when\n forwarding somebody else's patch with the above rules for\n D-C-O. Indeed you are encouraged to do so. Do not forget to\n place an in-body \"From: \" line at the beginning to properly attribute\n@@ -433,7 +433,7 @@ your patch differs from project to project, so it may be different\n from that of the project you are accustomed to.\n \n [[real-name]]\n-Please use a known identity in the `Signed-off-by` trailer, since we cannot\n+Please use a known identity in the `Signed-off-by:` trailer, since we cannot\n accept anonymous contributions. It is common, but not required, to use some form\n of your real name. We realize that some contributors are not comfortable doing\n so or prefer to contribute under a pseudonym or preferred name and we can accept\n@@ -488,7 +488,7 @@ Other projects might regularly refer to other kinds of data, like\n particular are not used in this project.\n \n Only capitalize the very first letter of the trailer, i.e. favor\n-\"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n+`Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.\n \n [[ai]]\n === Use of Artificial Intelligence (AI)\n@@ -610,7 +610,7 @@ Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n how to submit updated versions of a patch series.\n \n If your log message (including your name on the\n-`Signed-off-by` trailer) is not writable in ASCII, make sure that\n+`Signed-off-by:` trailer) is not writable in ASCII, make sure that\n you send off a message in the correct encoding.\n \n WARNING: Be wary of your MUAs word-wrap\n@@ -630,7 +630,7 @@ previously sent.\n The `git format-patch` command follows the best current practice to\n format the body of an e-mail message. At the beginning of the\n patch should come your commit message, ending with the\n-`Signed-off-by` trailers, and a line that consists of three dashes,\n+`Signed-off-by:` trailers, and a line that consists of three dashes,\n followed by the diffstat information and the patch itself. If\n you are forwarding a patch from somebody else, optionally, at\n the beginning of the e-mail message just before the commit\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545215","messageId":"trailer_order_matters.8f9@msgid.xyz","threadId":"65789","inReplyTo":"CV_SubPatches_trailers.8f3@msgid.xyz","subject":"[PATCH 6/6] SubmittingPatches: note that trailer order matters","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-10T22:22:49Z","receivedAt":"2026-06-10T22:25:06Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nIt matters where you put the s-o-b; it should be last. You are signing\noff on the patch as well as the whole message up to that point.\n\nThis also makes it clear who added what:\n\n Acked-by: The Reviewer \n Signed-off-by: The Contributor \n Acked-by: The (Late) Reviewer \n Signed-off-by: The Maintainer \n\nThe the first ack was added by the contributor and the second one was\nadded by the maintainer.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/SubmittingPatches | 5 +++++\n 1 file changed, 5 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 3d2e9ecfbb8..2045708bdf5 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -490,6 +490,11 @@ particular are not used in this project.\n Only capitalize the very first letter of the trailer, i.e. favor\n `Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.\n \n+Note that these trailers should come before your `Signed-off-by:`\n+trailer. You are signing off to the patch as well as the message. This\n+also makes it clear who added trailers when multiple people have signed\n+off on a patch.\n+\n [[ai]]\n === Use of Artificial Intelligence (AI)\n \n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545217","messageId":"xmqq8q8mt4eo.fsf@gitster.g","threadId":"65789","inReplyTo":"trailer_order_matters.8f9@msgid.xyz","subject":"Re: [PATCH 6/6] SubmittingPatches: note that trailer order matters","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-10T22:30:07Z","receivedAt":"2026-06-10T22:30:10Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> It matters where you put the s-o-b; it should be last. You are signing\n> off on the patch as well as the whole message up to that point.\n>\n> This also makes it clear who added what:\n>\n> Acked-by: The Reviewer \n> Signed-off-by: The Contributor \n> Acked-by: The (Late) Reviewer \n> Signed-off-by: The Maintainer \n>\n> The the first ack was added by the contributor and the second one was\n> added by the maintainer.\n>\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n> Documentation/SubmittingPatches | 5 +++++\n> 1 file changed, 5 insertions(+)\n>\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 3d2e9ecfbb8..2045708bdf5 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -490,6 +490,11 @@ particular are not used in this project.\n> Only capitalize the very first letter of the trailer, i.e. favor\n> `Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.\n> \n> +Note that these trailers should come before your `Signed-off-by:`\n> +trailer. You are signing off to the patch as well as the message. This\n> +also makes it clear who added trailers when multiple people have signed\n> +off on a patch.\n\nPerhaps first mention the underlying rule that they are added in the\norder that helps us to understand the chronological order of events.\nThat would avoid giving a wrong impression that the nature of each\ntrailer keys determine the order of these lines.\n\nThanks.\n"},{"id":"545299","messageId":"xmqq1pedowl2.fsf@gitster.g","threadId":"65789","inReplyTo":"encourage_substantial.8f4@msgid.xyz","subject":"Re: [PATCH 1/6] SubmittingPatches: encourage trailer use for substantial help","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-11T16:44:57Z","receivedAt":"2026-06-11T16:44:59Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> Let’s replace “If you like” with outright encouragment in this section\n\n\"encouragement\"?\n\n> At the same, it is important to temper this recommendation to a sign-\n> ificant enough contribution; in my experience beginners can be eager\n\n\"At the same time\"?\n\nIt is a bit unusual to see a long word split at the end of a line\nto line-wrap in our documentation and commit log messages.\n\n> ---\n> Documentation/SubmittingPatches | 14 +++++++++++---\n> 1 file changed, 11 insertions(+), 3 deletions(-)\n\nThe patch text itself looks great. Thanks.\n"},{"id":"545300","messageId":"xmqqwlw5nhxz.fsf@gitster.g","threadId":"65789","inReplyTo":"discourage_Linux.8f6@msgid.xyz","subject":"Re: [PATCH 3/6] SubmittingPatches: discourage common Linux trailers","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-11T16:46:32Z","receivedAt":"2026-06-11T16:46:34Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> This project does regularly mention what commits a patch/commit fixes,\n> but that is done inline in the commit message proper (c.f. the trailer\n> block of the message).\n\n\"cf.\"?\n\n> Link: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/ [2]\n\n;-)\n\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n> Documentation/SubmittingPatches | 4 ++++\n> 1 file changed, 4 insertions(+)\n>\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 51c308a89a8..5dc32128883 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -479,6 +479,10 @@ to be accepted since these are the most common ones. But another kind of\n> trailer might be relevant, for example to link to an issue tracker\n> belonging to a downstream project that is affected by a bug in Git.\n> \n> +Other projects might regularly refer to other kinds of data, like\n> +`Fixes:` and `Link:` in the Linux Kernel project, but these ones in\n> +particular are not used in this project.\n> +\n> Only capitalize the very first letter of the trailer, i.e. favor\n> \"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n"},{"id":"545301","messageId":"xmqqse6tnho1.fsf@gitster.g","threadId":"65789","inReplyTo":"Based-on-patch-by.8f7@msgid.xyz","subject":"Re: [PATCH 4/6] SubmittingPatches: document Based-on-patch-by trailer","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-11T16:52:30Z","receivedAt":"2026-06-11T16:52:32Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> +. `Based-on-patch-by:` can be used when someone else authored parts of\n> + the patch that you are submitting. This might be relevant if someone\n> + sent a patch to the mailing list without a commit message or a\n> + `Signed-off-by:` and you have picked it up.\n\nHmph, this seems to encourage pick up material that come outside of\nthe usual DCO process, which should not be the intention of this\ndocument.\n\nUnless the changes are trivial enough to not be copyrightable, it\nmay be better to say \"... if someone submitted a preliminary patch or\na detailed code snippet with their sign-off\", plus encourage asking\nthe original author to sign-off if it initially came without, or\nsomething like that?\n\n> . `Helped-by:` is used to credit someone who suggested ideas for\n> changes without providing the precise changes in patch form.\n> . `Mentored-by:` is used to credit someone with helping develop a\n"},{"id":"545368","messageId":"aivvE6gVMGWhRbCB@pks.im","threadId":"65789","inReplyTo":"non-ident_trailers.8f5@msgid.xyz","subject":"Re: [PATCH 2/6] SubmittingPatches: discuss non-ident trailers","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-12T11:35:47Z","receivedAt":"2026-06-12T11:35:53Z","isPatch":true,"body":"On Thu, Jun 11, 2026 at 12:22:45AM +0200, kristofferhaugsbakk@fastmail.com wrote:\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 0b12badf86d..51c308a89a8 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -474,7 +474,10 @@ These are the common trailers in use:\n> \n> While you can also create your own trailer if the situation warrants it, we\n> encourage you to instead use one of the common trailers in this project\n> -highlighted above.\n> +highlighted above. A trailer that credits someone might be more likely\n> +to be accepted since these are the most common ones. But another kind of\n> +trailer might be relevant, for example to link to an issue tracker\n> +belonging to a downstream project that is affected by a bug in Git.\n\nHm, I wonder whether this is a bit too vague to really be helpful for a\nnewcomer. Instead of alluding to such trailers, wouldn't it be\npreferable if we added those as actual examples to the list of known\ntrailers and then tell folks that they can invent their own ones if\nthere is a good reason to do so?\n\nPatrick\n"},{"id":"545682","messageId":"43cd8c48-c933-4eef-a6c0-970c38885967@app.fastmail.com","threadId":"65789","inReplyTo":"aivvE6gVMGWhRbCB@pks.im","subject":"Re: [PATCH 2/6] SubmittingPatches: discuss non-ident trailers","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-16T20:02:46Z","receivedAt":"2026-06-16T20:03:08Z","isPatch":true,"body":"On Fri, Jun 12, 2026, at 13:35, Patrick Steinhardt wrote:\n> On Thu, Jun 11, 2026 at 12:22:45AM +0200,\n> kristofferhaugsbakk@fastmail.com wrote:\n>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n>> index 0b12badf86d..51c308a89a8 100644\n>> --- a/Documentation/SubmittingPatches\n>> +++ b/Documentation/SubmittingPatches\n>> @@ -474,7 +474,10 @@ These are the common trailers in use:\n>>\n>> While you can also create your own trailer if the situation warrants it, we\n>> encourage you to instead use one of the common trailers in this project\n>> -highlighted above.\n>> +highlighted above. A trailer that credits someone might be more likely\n>> +to be accepted since these are the most common ones. But another kind of\n>> +trailer might be relevant, for example to link to an issue tracker\n>> +belonging to a downstream project that is affected by a bug in Git.\n>\n> Hm, I wonder whether this is a bit too vague to really be helpful for a\n> newcomer. Instead of alluding to such trailers, wouldn't it be\n> preferable if we added those as actual examples to the list of known\n> trailers and then tell folks that they can invent their own ones if\n> there is a good reason to do so?\n\nHonestly there are so few non-ident trailers that I don’t think they can\nbe listed as common trailers:\n\n1. The Git project doesn’t need them (e.g. no bug tracker)\n2. They seem mostly for use by other projects (bug trackers again)\n\nWith this list:\n\n git log --format='%(trailers:only,keyonly)' | sort | uniq\n\nIf you filter out the ident-looking ones:\n\n grep -v --extended-regexp -- '-[Bb]y$'\n\nThere are few left. And some can be discarded:\n\n• Change-Id\n• Message-ID\n• Fixes (pointing to a commit)\n\nSo to address your point:\n\n1. Maybe this is so niche that it is not worth mentioning; or\n2. Maybe give a concrete example like `Closes: `?\n"},{"id":"545683","messageId":"e0bd8fb9-d34e-43d4-b3e0-f2a4b8d6a7a8@app.fastmail.com","threadId":"65789","inReplyTo":"xmqqse6tnho1.fsf@gitster.g","subject":"Re: [PATCH 4/6] SubmittingPatches: document Based-on-patch-by trailer","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-16T20:07:15Z","receivedAt":"2026-06-16T20:07:36Z","isPatch":true,"body":"On Thu, Jun 11, 2026, at 18:52, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> +. `Based-on-patch-by:` can be used when someone else authored parts of\n>> + the patch that you are submitting. This might be relevant if someone\n>> + sent a patch to the mailing list without a commit message or a\n>> + `Signed-off-by:` and you have picked it up.\n>\n> Hmph, this seems to encourage pick up material that come outside of\n> the usual DCO process, which should not be the intention of this\n> document.\n\nOh, I have misread the room on this subject. It would be better to drop\nthe mention of signoff here.\n\n>\n> Unless the changes are trivial enough to not be copyrightable, it\n> may be better to say \"... if someone submitted a preliminary patch or\n> a detailed code snippet with their sign-off\", plus encourage asking\n> the original author to sign-off if it initially came without, or\n> something like that?\n\nOkay, since they provided something concrete to copy (cf. Helped-by\nwhere they did not provide precise changes in patch form, according to\nthe below context), it’s best to mention that signoff is relevant here.\n\n>\n>> . `Helped-by:` is used to credit someone who suggested ideas for\n>> changes without providing the precise changes in patch form.\n>> . `Mentored-by:` is used to credit someone with helping develop a\n"},{"id":"545684","messageId":"310ef65e-b6c7-4d0c-a58a-0c88257143ba@app.fastmail.com","threadId":"65789","inReplyTo":"xmqq1pedowl2.fsf@gitster.g","subject":"Re: [PATCH 1/6] SubmittingPatches: encourage trailer use for substantial help","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-16T20:14:38Z","receivedAt":"2026-06-16T20:14:59Z","isPatch":true,"body":"On Thu, Jun 11, 2026, at 18:44, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> Let’s replace “If you like” with outright encouragment in this section\n>\n> \"encouragement\"?\n\nYep.\n\n>\n>> At the same, it is important to temper this recommendation to a sign-\n>> ificant enough contribution; in my experience beginners can be eager\n>\n> \"At the same time\"?\n\nYep.\n\n>\n> It is a bit unusual to see a long word split at the end of a line\n> to line-wrap in our documentation and commit log messages.\n\nA bit unusual is an understatement. I cannot find any other commit log\nmessage writers that have split a word on a syllable. All linebreaks\nthat I’ve found are on existing hyphens. Like\n\n ... multi-pack-\n indexes\n\nI’ll avoid this in the future.\n\n>\n>> ---\n>> Documentation/SubmittingPatches | 14 +++++++++++---\n>> 1 file changed, 11 insertions(+), 3 deletions(-)\n>\n> The patch text itself looks great. Thanks.\n\nThanks for going over these.\n"},{"id":"545685","messageId":"89776d4e-bc61-475f-a12d-167047ddf23e@app.fastmail.com","threadId":"65789","inReplyTo":"xmqq8q8mt4eo.fsf@gitster.g","subject":"Re: [PATCH 6/6] SubmittingPatches: note that trailer order matters","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-16T20:18:37Z","receivedAt":"2026-06-16T20:18:58Z","isPatch":true,"body":"On Thu, Jun 11, 2026, at 00:30, Junio C Hamano wrote:\n>>[snip]\n>> Only capitalize the very first letter of the trailer, i.e. favor\n>> `Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.\n>>\n>> +Note that these trailers should come before your `Signed-off-by:`\n>> +trailer. You are signing off to the patch as well as the message. This\n>> +also makes it clear who added trailers when multiple people have signed\n>> +off on a patch.\n>\n> Perhaps first mention the underlying rule that they are added in the\n> order that helps us to understand the chronological order of events.\n> That would avoid giving a wrong impression that the nature of each\n> trailer keys determine the order of these lines.\n\nYou’re right. It’s best to lead with the time-based order. That\nnaturally leads into the implication that we can easily read what\ntrailers that any given person added.\n\nI’ve seen discussions in the past about whether trailers ought to be\nsorted by *kind*, and maybe if first e.g. you should first have\nTested-by, then Reviewed-by, then Signed-off-by... best to not give such\nan impression by accident.\n\nThanks.\n"},{"id":"545738","messageId":"ajJNjOYMVDwL52zY@pks.im","threadId":"65789","inReplyTo":"43cd8c48-c933-4eef-a6c0-970c38885967@app.fastmail.com","subject":"Re: [PATCH 2/6] SubmittingPatches: discuss non-ident trailers","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-17T07:32:28Z","receivedAt":"2026-06-17T07:32:34Z","isPatch":true,"body":"On Tue, Jun 16, 2026 at 10:02:46PM +0200, Kristoffer Haugsbakk wrote:\n> On Fri, Jun 12, 2026, at 13:35, Patrick Steinhardt wrote:\n> > On Thu, Jun 11, 2026 at 12:22:45AM +0200,\n> > kristofferhaugsbakk@fastmail.com wrote:\n> >> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> >> index 0b12badf86d..51c308a89a8 100644\n> >> --- a/Documentation/SubmittingPatches\n> >> +++ b/Documentation/SubmittingPatches\n> >> @@ -474,7 +474,10 @@ These are the common trailers in use:\n> >>\n> >> While you can also create your own trailer if the situation warrants it, we\n> >> encourage you to instead use one of the common trailers in this project\n> >> -highlighted above.\n> >> +highlighted above. A trailer that credits someone might be more likely\n> >> +to be accepted since these are the most common ones. But another kind of\n> >> +trailer might be relevant, for example to link to an issue tracker\n> >> +belonging to a downstream project that is affected by a bug in Git.\n> >\n> > Hm, I wonder whether this is a bit too vague to really be helpful for a\n> > newcomer. Instead of alluding to such trailers, wouldn't it be\n> > preferable if we added those as actual examples to the list of known\n> > trailers and then tell folks that they can invent their own ones if\n> > there is a good reason to do so?\n> \n> Honestly there are so few non-ident trailers that I don’t think they can\n> be listed as common trailers:\n> \n> 1. The Git project doesn’t need them (e.g. no bug tracker)\n> 2. They seem mostly for use by other projects (bug trackers again)\n> \n> With this list:\n> \n> git log --format='%(trailers:only,keyonly)' | sort | uniq\n> \n> If you filter out the ident-looking ones:\n> \n> grep -v --extended-regexp -- '-[Bb]y$'\n> \n> There are few left. And some can be discarded:\n> \n> • Change-Id\n> • Message-ID\n> • Fixes (pointing to a commit)\n> \n> So to address your point:\n> \n> 1. Maybe this is so niche that it is not worth mentioning; or\n> 2. Maybe give a concrete example like `Closes: `?\n\nWell, we don't use \"Closes:\" trailers, either. So I'd rather side with\nyour (1) and just not mention them at all.\n\nPatrick\n"},{"id":"545793","messageId":"c8317b15-1fac-4b29-bc1b-9a63e69e45e3@app.fastmail.com","threadId":"65789","inReplyTo":"ajJNjOYMVDwL52zY@pks.im","subject":"Re: [PATCH 2/6] SubmittingPatches: discuss non-ident trailers","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-17T19:43:23Z","receivedAt":"2026-06-17T19:43:46Z","isPatch":true,"body":"On Wed, Jun 17, 2026, at 09:32, Patrick Steinhardt wrote:\n> On Tue, Jun 16, 2026 at 10:02:46PM +0200, Kristoffer Haugsbakk wrote:\n>> On Fri, Jun 12, 2026, at 13:35, Patrick Steinhardt wrote:\n>> >>[snip]\n>> >\n>> > Hm, I wonder whether this is a bit too vague to really be helpful for a\n>> > newcomer. Instead of alluding to such trailers, wouldn't it be\n>> > preferable if we added those as actual examples to the list of known\n>> > trailers and then tell folks that they can invent their own ones if\n>> > there is a good reason to do so?\n>>\n>> Honestly there are so few non-ident trailers that I don’t think they can\n>> be listed as common trailers:\n>>\n>> 1. The Git project doesn’t need them (e.g. no bug tracker)\n>> 2. They seem mostly for use by other projects (bug trackers again)\n>>\n>> With this list:\n>>\n>> git log --format='%(trailers:only,keyonly)' | sort | uniq\n>>\n>> If you filter out the ident-looking ones:\n>>\n>> grep -v --extended-regexp -- '-[Bb]y$'\n>>\n>> There are few left. And some can be discarded:\n>>\n>> • Change-Id\n>> • Message-ID\n>> • Fixes (pointing to a commit)\n>>\n>> So to address your point:\n>>\n>> 1. Maybe this is so niche that it is not worth mentioning; or\n>> 2. Maybe give a concrete example like `Closes: `?\n>\n> Well, we don't use \"Closes:\" trailers, either. So I'd rather side with\n> your (1) and just not mention them at all.\n\nYeah, I think this can just be dropped. Thanks.\n"},{"id":"545799","messageId":"V2_CV_SubPatches_trailers.9b6@msgid.xyz","threadId":"65789","inReplyTo":"CV_SubPatches_trailers.8f3@msgid.xyz","subject":"[PATCH v2 0/5] SubmittingPatches: update and flesh out trailer sections","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-17T20:52:14Z","receivedAt":"2026-06-17T20:52:32Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name (applied) kh/submittingpatches-trailers\n\nTopic summary: Flesh out and update the trailer sections.\n\nAll of these points have come up on the mailing list. At least for me.\nAnd `Based-on-patch-by` is a nice-to-have documented kind of thing.\n\n[elide “since January” from v1...]\n\nLink to v1: https://lore.kernel.org/git/CV_SubPatches_trailers.8f3@msgid.xyz/\n\n§ Changes in v2\n\nSee the patch Notes for details.\n\n• Improve commit messages\n• Drop patch “discuss non-ident trailers”\n • https://lore.kernel.org/git/CV_SubPatches_trailers.8f3@msgid.xyz/T/#m53305dbb8c1f19b06be781ee720fc3be875a326d\n• Rewrite “note that trailer order matters” to emphasize chronological\n order and to also mention it in the DCO section\n • See https://lore.kernel.org/git/xmqq8q8mt4eo.fsf@gitster.g/\n\n[1/5] SubmittingPatches: encourage trailer use for substantial help\n[2/5] SubmittingPatches: discourage common Linux trailers\n[3/5] SubmittingPatches: document Based-on-patch-by trailer\n[4/5] SubmittingPatches: be consistent with trailer markup\n[5/5] SubmittingPatches: note that trailer order matters\n\n Documentation/SubmittingPatches | 46 ++++++++++++++++++++++++++-------\n 1 file changed, 36 insertions(+), 10 deletions(-)\n\nInterdiff against v1:\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 89542263444..dceeb5a1817 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -427,6 +427,10 @@ D-C-O. Indeed you are encouraged to do so. Do not forget to\n place an in-body \"From: \" line at the beginning to properly attribute\n the change to its true author (see (2) above).\n \n+Place this `Signed-off-by:` trailer at the end, after trailers added by\n+others and after other trailers added by you; see\n+<> below (\"chronological order\").\n+\n This procedure originally came from the Linux kernel project, so our\n rule is quite similar to theirs, but what exactly it means to sign-off\n your patch differs from project to project, so it may be different\n@@ -467,8 +471,8 @@ These are the common trailers in use:\n of a patch before submitting it.\n . `Based-on-patch-by:` is used when someone else authored parts of the\n patch that you are submitting. This might be relevant if someone sent\n- a patch to the mailing list without a commit message or a\n- `Signed-off-by:` and you have picked it up.\n+ a patch to the mailing list with their sign-off. (Be mindful and ask\n+ them to sign off on it if they did not.)\n . `Helped-by:` is used to credit someone who suggested ideas for\n changes without providing the precise changes in patch form.\n . `Mentored-by:` is used to credit someone with helping develop a\n@@ -478,10 +482,7 @@ These are the common trailers in use:\n \n While you can also create your own trailer if the situation warrants it, we\n encourage you to instead use one of the common trailers in this project\n-highlighted above. A trailer that credits someone might be more likely\n-to be accepted since these are the most common ones. But another kind of\n-trailer might be relevant, for example to link to an issue tracker\n-belonging to a downstream project that is affected by a bug in Git.\n+highlighted above.\n \n Other projects might regularly refer to other kinds of data, like\n `Fixes:` and `Link:` in the Linux Kernel project, but these ones in\n@@ -490,10 +491,11 @@ particular are not used in this project.\n Only capitalize the very first letter of the trailer, i.e. favor\n `Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.\n \n-Note that these trailers should come before your `Signed-off-by:`\n-trailer. You are signing off to the patch as well as the message. This\n-also makes it clear who added trailers when multiple people have signed\n-off on a patch.\n+As mentioned under <> above, trailers are added in\n+chronological order; one person might sign-off on a patch and send it to\n+someone else, who then in turn adds her own sign-off. Further, any\n+trailers that you add beyond your sign-off should come before that\n+sign-off. That makes it clear what trailers which person added.\n \n [[ai]]\n === Use of Artificial Intelligence (AI)\nRange-diff against v1:\n1: 366c0f43b71 ! 1: 835eb736f39 SubmittingPatches: encourage trailer use for substantial help\n @@ Commit message\n contribution”.[2]\n \n Adding trailers is already encouraged, but in the section `send-patches`.\n - Let’s replace “If you like” with outright encouragment in this section\n + Let’s replace “If you like” with outright encouragement in this section\n so that all trailer discussion (except s-o-b; see `sign-off` section) is\n contained in this section; a link to from `send-patches` makes this\n information equally visible.\n @@ Commit message\n Now we need to make a heading for `commit-trailers` in order for the\n HTML output to make sense.\n \n - At the same, it is important to temper this recommendation to a sign-\n - ificant enough contribution; in my experience beginners can be eager\n + At the same time, it is important to temper this recommendation to a\n + significant enough contribution; in my experience beginners can be eager\n to add a trailer for everyone who replies with an action point that is\n followed up on.\n \n2: c78fb49c245 < -: ----------- SubmittingPatches: discuss non-ident trailers\n3: cff069ced4e ! 2: 5a652b8e14d SubmittingPatches: discourage common Linux trailers\n @@ Commit message\n git.git `master` from time to time.\n \n This project does regularly mention what commits a patch/commit fixes,\n - but that is done inline in the commit message proper (c.f. the trailer\n + but that is done inline in the commit message proper (cf. the trailer\n block of the message).\n \n For `Link`: These are used both to link back to the patch submission as\n @@ Commit message\n Signed-off-by: Kristoffer Haugsbakk \n \n ## Documentation/SubmittingPatches ##\n -@@ Documentation/SubmittingPatches: to be accepted since these are the most common ones. But another kind of\n - trailer might be relevant, for example to link to an issue tracker\n - belonging to a downstream project that is affected by a bug in Git.\n +@@ Documentation/SubmittingPatches: While you can also create your own trailer if the situation warrants it, we\n + encourage you to instead use one of the common trailers in this project\n + highlighted above.\n \n +Other projects might regularly refer to other kinds of data, like\n +`Fixes:` and `Link:` in the Linux Kernel project, but these ones in\n4: 278eb2c5d21 ! 3: 5e53999b2e9 SubmittingPatches: document Based-on-patch-by trailer\n @@ Documentation/SubmittingPatches: These are the common trailers in use:\n of a patch before submitting it.\n +. `Based-on-patch-by:` is used when someone else authored parts of the\n + patch that you are submitting. This might be relevant if someone sent\n -+ a patch to the mailing list without a commit message or a\n -+ `Signed-off-by:` and you have picked it up.\n ++ a patch to the mailing list with their sign-off. (Be mindful and ask\n ++ them to sign off on it if they did not.)\n . `Helped-by:` is used to credit someone who suggested ideas for\n changes without providing the precise changes in patch form.\n . `Mentored-by:` is used to credit someone with helping develop a\n5: 347c72e4e08 = 4: dd47fabe917 SubmittingPatches: be consistent with trailer markup\n6: 1c7e9ad8e69 ! 5: 20f04e18cee SubmittingPatches: note that trailer order matters\n @@ Metadata\n ## Commit message ##\n SubmittingPatches: note that trailer order matters\n \n - It matters where you put the s-o-b; it should be last. You are signing\n - off on the patch as well as the whole message up to that point.\n + It matters where you put new trailers: they should be added in\n + chronological order, and each person who passes on a patch should add\n + their s-o-b last. You are signing off on the patch as well as the whole\n + message up to that point.\n \n This also makes it clear who added what:\n \n @@ Commit message\n Acked-by: The (Late) Reviewer \n Signed-off-by: The Maintainer \n \n - The the first ack was added by the contributor and the second one was\n - added by the maintainer.\n + The first ack was added by the contributor and the second one was added\n + by the maintainer.\n \n + Helped-by: Junio C Hamano \n Signed-off-by: Kristoffer Haugsbakk \n \n ## Documentation/SubmittingPatches ##\n +@@ Documentation/SubmittingPatches: D-C-O. Indeed you are encouraged to do so. Do not forget to\n + place an in-body \"From: \" line at the beginning to properly attribute\n + the change to its true author (see (2) above).\n + \n ++Place this `Signed-off-by:` trailer at the end, after trailers added by\n ++others and after other trailers added by you; see\n ++<> below (\"chronological order\").\n ++\n + This procedure originally came from the Linux kernel project, so our\n + rule is quite similar to theirs, but what exactly it means to sign-off\n + your patch differs from project to project, so it may be different\n @@ Documentation/SubmittingPatches: particular are not used in this project.\n Only capitalize the very first letter of the trailer, i.e. favor\n `Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.\n \n -+Note that these trailers should come before your `Signed-off-by:`\n -+trailer. You are signing off to the patch as well as the message. This\n -+also makes it clear who added trailers when multiple people have signed\n -+off on a patch.\n ++As mentioned under <> above, trailers are added in\n ++chronological order; one person might sign-off on a patch and send it to\n ++someone else, who then in turn adds her own sign-off. Further, any\n ++trailers that you add beyond your sign-off should come before that\n ++sign-off. That makes it clear what trailers which person added.\n +\n [[ai]]\n === Use of Artificial Intelligence (AI)\n\nbase-commit: 1ff279f3404a482a83fb04c7457e41ab26884aea\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545800","messageId":"V2_encourage_substantial.9b7@msgid.xyz","threadId":"65789","inReplyTo":"V2_CV_SubPatches_trailers.9b6@msgid.xyz","subject":"[PATCH v2 1/5] SubmittingPatches: encourage trailer use for substantial help","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-17T20:52:15Z","receivedAt":"2026-06-17T20:52:50Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTrailers beyond the mandatory s-o-b are regularly used based on my\nlast two years of reading the mailing list. Moreover, reviewers might\nencourage it.[1]\n\nThis is also in line with the project crediting both commit authors and\npeople mentioned in trailers each release; “Nobody is THE one making\ncontribution”.[2]\n\nAdding trailers is already encouraged, but in the section `send-patches`.\nLet’s replace “If you like” with outright encouragement in this section\nso that all trailer discussion (except s-o-b; see `sign-off` section) is\ncontained in this section; a link to from `send-patches` makes this\ninformation equally visible.\n\nNow we need to make a heading for `commit-trailers` in order for the\nHTML output to make sense.\n\nAt the same time, it is important to temper this recommendation to a\nsignificant enough contribution; in my experience beginners can be eager\nto add a trailer for everyone who replies with an action point that is\nfollowed up on.\n\nLet’s also spell out that these trailers should follow the Git author/\ncommitter format. One might naturally just write the name, but in that\ncase it will not be picked up by:\n\n git shortlog --group=trailer:\n\nand normalization via `.mailmap` will not work.\n\nAlso introduce the list of common trailers as such. Granted, this is\nalready implied by the later paragraph about “create your own trailer”,\nso this just frontloads this information.\n\n† 1: https://lore.kernel.org/git/CAP8UFD0POvYDgGtEx8GBhvKkd8XzzWQsy8XxAKL9M3+uz3ka+w@mail.gmail.com/#:~:text=for%20at%20least\n† 2: https://lore.kernel.org/git/xmqqzh248sy0.fsf@gitster.c.googlers.com/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Msg: proofreading typos, dropped words[1]\n • Msg: Avoid hyphenating for linebreaks on syllable[1]\n 🔗 1: https://lore.kernel.org/git/310ef65e-b6c7-4d0c-a58a-0c88257143ba@app.fastmail.com/\n\n Documentation/SubmittingPatches | 14 +++++++++++---\n 1 file changed, 11 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 176567738d4..0b12badf86d 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -443,8 +443,16 @@ identifying, and not misleading.\n The goal of this policy is to allow us to have sufficient information to contact\n you if questions arise about your contribution.\n \n+=== Commit trailers\n [[commit-trailers]]\n-If you like, you can put extra trailers at the end:\n+It is polite to credit people who have helped with your work to a\n+substantial enough degree. This project uses commit trailers for that,\n+where the credited person is written out like a Git author, i.e. with\n+both their name and their email address. Note that the threshold to\n+credit someone is a judgement call, and crediting someone for simple\n+review work is certainly not necessary.\n+\n+These are the common trailers in use:\n \n . `Reported-by:` is used to credit someone who found the bug that\n the patch attempts to fix.\n@@ -562,8 +570,8 @@ when the maintainer did not heavily participate in the discussion and\n instead left the review to trusted others.\n \n Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and\n-`Tested-by:` lines as necessary to credit people who helped your\n-patch, and \"cc:\" them when sending such a final version for inclusion.\n+`Tested-by:` (see <>), and \"cc:\" them\n+when sending such a final version for inclusion.\n \n ==== `format-patch` and `send-email`\n \n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545801","messageId":"V2_discourage_Linux.9b8@msgid.xyz","threadId":"65789","inReplyTo":"V2_CV_SubPatches_trailers.9b6@msgid.xyz","subject":"[PATCH v2 2/5] SubmittingPatches: discourage common Linux trailers","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-17T20:52:16Z","receivedAt":"2026-06-17T20:53:09Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThe Linux Kernel regularly uses trailers (or “tags”) `Fixes` and\n`Link`. Sometimes people submit patches to this project with them.\nThey have their use in that project but it is not clear what purpose\nthey would serve here.\n\nFor `Fixes`: Linux has many trees, and applying patches with\ncherry-picks is common. A `Fixes` trailer in commit C2 pointing to\ncommit C1 helps the cherry-picker figure out that she probably needs\nC2 if she wants to apply C1. See linux/d5d6281a (checkpatch: check for\nmissing Fixes tags, 2024-06-11):[1]\n\n Why are stable patches encouraged to have a fixes tag? Some people\n mark their stable patches as \"# 5.10\" etc. This is useful but a\n Fixes tag is still a good idea. For example, the Fixes tag helps in\n review. It helps people to not cherry-pick buggy patches without\n also cherry-picking the fix.\n\nIn contrast the Git project has few trees (to my knowledge), and there\nis much less need to cherry-pick fixes as opposed to either using\nbackmerges or rebasing all of the downstream tree’s commits on top of\ngit.git `master` from time to time.\n\nThis project does regularly mention what commits a patch/commit fixes,\nbut that is done inline in the commit message proper (cf. the trailer\nblock of the message).\n\nFor `Link`: These are used both to link back to the patch submission as\nwell as with footnotes. In contrast this project has `refs/notes/amlog`\nfor linking back to the patch submissions, and footnotes are only used\nin the commit message proper.\n\n† 1: Commit linux/d5d6281a has “linux” in front of it since this commit\n is from the Linux Kernel, not Git. Example of a Linux tree—as well\n as an example of `Link`—is [2].\n\nLink: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/ [2]\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: Msg: it’s “cf.”, not “c.f.”\n\n Documentation/SubmittingPatches | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 0b12badf86d..38e18982aa2 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -476,6 +476,10 @@ While you can also create your own trailer if the situation warrants it, we\n encourage you to instead use one of the common trailers in this project\n highlighted above.\n \n+Other projects might regularly refer to other kinds of data, like\n+`Fixes:` and `Link:` in the Linux Kernel project, but these ones in\n+particular are not used in this project.\n+\n Only capitalize the very first letter of the trailer, i.e. favor\n \"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n \n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545802","messageId":"V2_Based-on-patch-by.9b9@msgid.xyz","threadId":"65789","inReplyTo":"V2_CV_SubPatches_trailers.9b6@msgid.xyz","subject":"[PATCH v2 3/5] SubmittingPatches: document Based-on-patch-by trailer","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-17T20:52:17Z","receivedAt":"2026-06-17T20:53:26Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis trailer comes up often enough and the use case is not fully covered\nby the other trailers here. For example, it is sometimes better to use\nthis trailer instead of `Co-authored-by:`.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Do *not* say *without sign-off*; do mention the precondition that\n it is signed off, and cover the case when the patch author did not\n sign off on it\n • https://lore.kernel.org/git/xmqqse6tnho1.fsf@gitster.g/\n • Drop “without a commit message”. It doesn’t seem important. A bare\n patch is just a patch, not a patch plus a message.\n\n Documentation/SubmittingPatches | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 38e18982aa2..4a37bc29f5a 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -465,6 +465,10 @@ These are the common trailers in use:\n and found it to have the desired effect.\n . `Co-authored-by:` is used to indicate that people exchanged drafts\n of a patch before submitting it.\n+. `Based-on-patch-by:` is used when someone else authored parts of the\n+ patch that you are submitting. This might be relevant if someone sent\n+ a patch to the mailing list with their sign-off. (Be mindful and ask\n+ them to sign off on it if they did not.)\n . `Helped-by:` is used to credit someone who suggested ideas for\n changes without providing the precise changes in patch form.\n . `Mentored-by:` is used to credit someone with helping develop a\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545803","messageId":"V2_just_trailer_markup.9ba@msgid.xyz","threadId":"65789","inReplyTo":"V2_CV_SubPatches_trailers.9b6@msgid.xyz","subject":"[PATCH v2 4/5] SubmittingPatches: be consistent with trailer markup","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-17T20:52:18Z","receivedAt":"2026-06-17T20:53:45Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThe rest of this section and (most importantly) the list has decided to\nuse `:`. So let’s use backticks (`) and a colon (:) throughout the\ndocument.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/SubmittingPatches | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 4a37bc29f5a..cb2df3cfff6 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -374,7 +374,7 @@ or, on an older version of Git without support for --pretty=reference:\n ....\n \n [[sign-off]]\n-=== Certify your work by adding your `Signed-off-by` trailer\n+=== Certify your work by adding your `Signed-off-by:` trailer\n \n To improve tracking of who did what, we ask you to certify that you\n wrote the patch or have the right to pass it on under the same license\n@@ -411,7 +411,7 @@ d. I understand and agree that this project and the contribution\n this project or the open source license(s) involved.\n ____\n \n-you add a \"Signed-off-by\" trailer to your commit, that looks like\n+you add a `Signed-off-by:` trailer to your commit, that looks like\n this:\n \n ....\n@@ -421,7 +421,7 @@ this:\n This line can be added by Git if you run the git-commit command with\n the -s option.\n \n-Notice that you can place your own `Signed-off-by` trailer when\n+Notice that you can place your own `Signed-off-by:` trailer when\n forwarding somebody else's patch with the above rules for\n D-C-O. Indeed you are encouraged to do so. Do not forget to\n place an in-body \"From: \" line at the beginning to properly attribute\n@@ -433,7 +433,7 @@ your patch differs from project to project, so it may be different\n from that of the project you are accustomed to.\n \n [[real-name]]\n-Please use a known identity in the `Signed-off-by` trailer, since we cannot\n+Please use a known identity in the `Signed-off-by:` trailer, since we cannot\n accept anonymous contributions. It is common, but not required, to use some form\n of your real name. We realize that some contributors are not comfortable doing\n so or prefer to contribute under a pseudonym or preferred name and we can accept\n@@ -485,7 +485,7 @@ Other projects might regularly refer to other kinds of data, like\n particular are not used in this project.\n \n Only capitalize the very first letter of the trailer, i.e. favor\n-\"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n+`Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.\n \n [[ai]]\n === Use of Artificial Intelligence (AI)\n@@ -607,7 +607,7 @@ Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n how to submit updated versions of a patch series.\n \n If your log message (including your name on the\n-`Signed-off-by` trailer) is not writable in ASCII, make sure that\n+`Signed-off-by:` trailer) is not writable in ASCII, make sure that\n you send off a message in the correct encoding.\n \n WARNING: Be wary of your MUAs word-wrap\n@@ -627,7 +627,7 @@ previously sent.\n The `git format-patch` command follows the best current practice to\n format the body of an e-mail message. At the beginning of the\n patch should come your commit message, ending with the\n-`Signed-off-by` trailers, and a line that consists of three dashes,\n+`Signed-off-by:` trailers, and a line that consists of three dashes,\n followed by the diffstat information and the patch itself. If\n you are forwarding a patch from somebody else, optionally, at\n the beginning of the e-mail message just before the commit\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545804","messageId":"V2_trailer_order_matters.9bb@msgid.xyz","threadId":"65789","inReplyTo":"V2_CV_SubPatches_trailers.9b6@msgid.xyz","subject":"[PATCH v2 5/5] SubmittingPatches: note that trailer order matters","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-17T20:52:19Z","receivedAt":"2026-06-17T20:54:04Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nIt matters where you put new trailers: they should be added in\nchronological order, and each person who passes on a patch should add\ntheir s-o-b last. You are signing off on the patch as well as the whole\nmessage up to that point.\n\nThis also makes it clear who added what:\n\n Acked-by: The Reviewer \n Signed-off-by: The Contributor \n Acked-by: The (Late) Reviewer \n Signed-off-by: The Maintainer \n\nThe first ack was added by the contributor and the second one was added\nby the maintainer.\n\nHelped-by: Junio C Hamano \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Mention this in both the DCO section (new) as well as the trailers\n section\n • Emphasize and lead with chronological order and let everything\n fall in place according to that\n • https://lore.kernel.org/git/xmqq8q8mt4eo.fsf@gitster.g/\n • Msg: Drop “the the”; one is enough\n\n Documentation/SubmittingPatches | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex cb2df3cfff6..dceeb5a1817 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -427,6 +427,10 @@ D-C-O. Indeed you are encouraged to do so. Do not forget to\n place an in-body \"From: \" line at the beginning to properly attribute\n the change to its true author (see (2) above).\n \n+Place this `Signed-off-by:` trailer at the end, after trailers added by\n+others and after other trailers added by you; see\n+<> below (\"chronological order\").\n+\n This procedure originally came from the Linux kernel project, so our\n rule is quite similar to theirs, but what exactly it means to sign-off\n your patch differs from project to project, so it may be different\n@@ -487,6 +491,12 @@ particular are not used in this project.\n Only capitalize the very first letter of the trailer, i.e. favor\n `Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.\n \n+As mentioned under <> above, trailers are added in\n+chronological order; one person might sign-off on a patch and send it to\n+someone else, who then in turn adds her own sign-off. Further, any\n+trailers that you add beyond your sign-off should come before that\n+sign-off. That makes it clear what trailers which person added.\n+\n [[ai]]\n === Use of Artificial Intelligence (AI)\n \n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545805","messageId":"xmqq4ij0vo8f.fsf@gitster.g","threadId":"65789","inReplyTo":"V2_encourage_substantial.9b7@msgid.xyz","subject":"Re: [PATCH v2 1/5] SubmittingPatches: encourage trailer use for substantial help","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-17T21:41:36Z","receivedAt":"2026-06-17T21:41:39Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n> index 176567738d4..0b12badf86d 100644\n> --- a/Documentation/SubmittingPatches\n> +++ b/Documentation/SubmittingPatches\n> @@ -443,8 +443,16 @@ identifying, and not misleading.\n> The goal of this policy is to allow us to have sufficient information to contact\n> you if questions arise about your contribution.\n> \n> +=== Commit trailers\n> [[commit-trailers]]\n> -If you like, you can put extra trailers at the end:\n\nI think majority of AsciiDoc files in this project places [[anchor]]\nbefore the \"=== title\" of a section. For example, here is how the\npatch flow section begins in SubmittingPatches:\n\n [[patch-flow]]\n === A typical life cycle of a patch series\n\n To help us understand the reason behind various guidelines given later\n in the document, first let's understand how the life cycle of a\n typical patch series for this project goes.\n\nI do not offhand know which way is kosher, but we should be\nconsistent either way.\n\nThanks.\n"},{"id":"545837","messageId":"afc9c132-252f-41de-bd20-7f3ed5fc136f@app.fastmail.com","threadId":"65789","inReplyTo":"xmqq4ij0vo8f.fsf@gitster.g","subject":"Re: [PATCH v2 1/5] SubmittingPatches: encourage trailer use for substantial help","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-18T12:21:28Z","receivedAt":"2026-06-18T12:21:50Z","isPatch":true,"body":"On Wed, Jun 17, 2026, at 23:41, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\n>> index 176567738d4..0b12badf86d 100644\n>> --- a/Documentation/SubmittingPatches\n>> +++ b/Documentation/SubmittingPatches\n>> @@ -443,8 +443,16 @@ identifying, and not misleading.\n>> The goal of this policy is to allow us to have sufficient information to contact\n>> you if questions arise about your contribution.\n>>\n>> +=== Commit trailers\n>> [[commit-trailers]]\n>> -If you like, you can put extra trailers at the end:\n>\n> I think majority of AsciiDoc files in this project places [[anchor]]\n> before the \"=== title\" of a section. For example, here is how the\n> patch flow section begins in SubmittingPatches:\n>\n> [[patch-flow]]\n> === A typical life cycle of a patch series\n>\n> To help us understand the reason behind various guidelines given later\n> in the document, first let's understand how the life cycle of a\n> typical patch series for this project goes.\n>\n> I do not offhand know which way is kosher, but we should be\n> consistent either way.\n\nYour suspicion is correct. Skimming this I cannot seem to find any\nexamples where the anchor goes after the title.\n\n git grep --extended-regexp -C1 '^\\[\\[' -- 'Documentation/*adoc'\n\nI’ll fix it.\n"},{"id":"545912","messageId":"V3_CV_SubPatches_trailers.9ec@msgid.xyz","threadId":"65789","inReplyTo":"CV_SubPatches_trailers.8f3@msgid.xyz","subject":"[PATCH v3 0/5] SubmittingPatches: update and flesh out trailer sections","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-19T05:44:49Z","receivedAt":"2026-06-19T05:45:35Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name (applied) kh/submittingpatches-trailers\n\nTopic summary: Flesh out and update the trailer sections.\n\nAll of these points have come up on the mailing list. At least for me.\nAnd `Based-on-patch-by` is a nice-to-have documented kind of thing.\n\n[elide “since January” from v1...]\n\nLink to v2: https://lore.kernel.org/git/V2_CV_SubPatches_trailers.9b6@msgid.xyz/\n\n§ Changes in v3\n\nPatch “encourage trailer use for substantial help”: correct AsciiDoc anchor\nplacement.\n\n[1/5] SubmittingPatches: encourage trailer use for substantial help\n[2/5] SubmittingPatches: discourage common Linux trailers\n[3/5] SubmittingPatches: document Based-on-patch-by trailer\n[4/5] SubmittingPatches: be consistent with trailer markup\n[5/5] SubmittingPatches: note that trailer order matters\n\n Documentation/SubmittingPatches | 46 ++++++++++++++++++++++++++-------\n 1 file changed, 36 insertions(+), 10 deletions(-)\n\nInterdiff against v2:\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex dceeb5a1817..56706e55ea1 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -447,8 +447,8 @@ identifying, and not misleading.\n The goal of this policy is to allow us to have sufficient information to contact\n you if questions arise about your contribution.\n \n-=== Commit trailers\n [[commit-trailers]]\n+=== Commit trailers\n It is polite to credit people who have helped with your work to a\n substantial enough degree. This project uses commit trailers for that,\n where the credited person is written out like a Git author, i.e. with\nRange-diff against v2:\n1: 835eb736f39 ! 1: dc75b862d73 SubmittingPatches: encourage trailer use for substantial help\n @@ Commit message\n Signed-off-by: Kristoffer Haugsbakk \n \n ## Documentation/SubmittingPatches ##\n -@@ Documentation/SubmittingPatches: identifying, and not misleading.\n - The goal of this policy is to allow us to have sufficient information to contact\n +@@ Documentation/SubmittingPatches: The goal of this policy is to allow us to have sufficient information to contact\n you if questions arise about your contribution.\n \n -+=== Commit trailers\n [[commit-trailers]]\n -If you like, you can put extra trailers at the end:\n ++=== Commit trailers\n +It is polite to credit people who have helped with your work to a\n +substantial enough degree. This project uses commit trailers for that,\n +where the credited person is written out like a Git author, i.e. with\n2: 5a652b8e14d = 2: 86b9973a8e8 SubmittingPatches: discourage common Linux trailers\n3: 5e53999b2e9 = 3: a142f66c3b8 SubmittingPatches: document Based-on-patch-by trailer\n4: dd47fabe917 = 4: 439fa864da7 SubmittingPatches: be consistent with trailer markup\n5: 726386d976b = 5: 2d133f2ad5e SubmittingPatches: note that trailer order matters\n\nbase-commit: 1ff279f3404a482a83fb04c7457e41ab26884aea\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545913","messageId":"V3_encourage_substantial.9ed@msgid.xyz","threadId":"65789","inReplyTo":"V3_CV_SubPatches_trailers.9ec@msgid.xyz","subject":"[PATCH v3 1/5] SubmittingPatches: encourage trailer use for substantial help","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-19T05:44:50Z","receivedAt":"2026-06-19T05:45:54Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTrailers beyond the mandatory s-o-b are regularly used based on my\nlast two years of reading the mailing list. Moreover, reviewers might\nencourage it.[1]\n\nThis is also in line with the project crediting both commit authors and\npeople mentioned in trailers each release; “Nobody is THE one making\ncontribution”.[2]\n\nAdding trailers is already encouraged, but in the section `send-patches`.\nLet’s replace “If you like” with outright encouragement in this section\nso that all trailer discussion (except s-o-b; see `sign-off` section) is\ncontained in this section; a link to from `send-patches` makes this\ninformation equally visible.\n\nNow we need to make a heading for `commit-trailers` in order for the\nHTML output to make sense.\n\nAt the same time, it is important to temper this recommendation to a\nsignificant enough contribution; in my experience beginners can be eager\nto add a trailer for everyone who replies with an action point that is\nfollowed up on.\n\nLet’s also spell out that these trailers should follow the Git author/\ncommitter format. One might naturally just write the name, but in that\ncase it will not be picked up by:\n\n git shortlog --group=trailer:\n\nand normalization via `.mailmap` will not work.\n\nAlso introduce the list of common trailers as such. Granted, this is\nalready implied by the later paragraph about “create your own trailer”,\nso this just frontloads this information.\n\n† 1: https://lore.kernel.org/git/CAP8UFD0POvYDgGtEx8GBhvKkd8XzzWQsy8XxAKL9M3+uz3ka+w@mail.gmail.com/#:~:text=for%20at%20least\n† 2: https://lore.kernel.org/git/xmqqzh248sy0.fsf@gitster.c.googlers.com/\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v3: correct anchor placement\n 🔗 https://lore.kernel.org/git/xmqq4ij0vo8f.fsf@gitster.g/\n v2:\n • Msg: proofreading typos, dropped words[1]\n • Msg: Avoid hyphenating for linebreaks on syllable[1]\n 🔗 1: https://lore.kernel.org/git/310ef65e-b6c7-4d0c-a58a-0c88257143ba@app.fastmail.com/\n\n Documentation/SubmittingPatches | 14 +++++++++++---\n 1 file changed, 11 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 176567738d4..4e8dea4eaa6 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -444,7 +444,15 @@ The goal of this policy is to allow us to have sufficient information to contact\n you if questions arise about your contribution.\n \n [[commit-trailers]]\n-If you like, you can put extra trailers at the end:\n+=== Commit trailers\n+It is polite to credit people who have helped with your work to a\n+substantial enough degree. This project uses commit trailers for that,\n+where the credited person is written out like a Git author, i.e. with\n+both their name and their email address. Note that the threshold to\n+credit someone is a judgement call, and crediting someone for simple\n+review work is certainly not necessary.\n+\n+These are the common trailers in use:\n \n . `Reported-by:` is used to credit someone who found the bug that\n the patch attempts to fix.\n@@ -562,8 +570,8 @@ when the maintainer did not heavily participate in the discussion and\n instead left the review to trusted others.\n \n Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and\n-`Tested-by:` lines as necessary to credit people who helped your\n-patch, and \"cc:\" them when sending such a final version for inclusion.\n+`Tested-by:` (see <>), and \"cc:\" them\n+when sending such a final version for inclusion.\n \n ==== `format-patch` and `send-email`\n \n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545914","messageId":"V3_discourage_Linux.9ee@msgid.xyz","threadId":"65789","inReplyTo":"V3_CV_SubPatches_trailers.9ec@msgid.xyz","subject":"[PATCH v3 2/5] SubmittingPatches: discourage common Linux trailers","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-19T05:44:51Z","receivedAt":"2026-06-19T05:46:13Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThe Linux Kernel regularly uses trailers (or “tags”) `Fixes` and\n`Link`. Sometimes people submit patches to this project with them.\nThey have their use in that project but it is not clear what purpose\nthey would serve here.\n\nFor `Fixes`: Linux has many trees, and applying patches with\ncherry-picks is common. A `Fixes` trailer in commit C2 pointing to\ncommit C1 helps the cherry-picker figure out that she probably needs\nC2 if she wants to apply C1. See linux/d5d6281a (checkpatch: check for\nmissing Fixes tags, 2024-06-11):[1]\n\n Why are stable patches encouraged to have a fixes tag? Some people\n mark their stable patches as \"# 5.10\" etc. This is useful but a\n Fixes tag is still a good idea. For example, the Fixes tag helps in\n review. It helps people to not cherry-pick buggy patches without\n also cherry-picking the fix.\n\nIn contrast the Git project has few trees (to my knowledge), and there\nis much less need to cherry-pick fixes as opposed to either using\nbackmerges or rebasing all of the downstream tree’s commits on top of\ngit.git `master` from time to time.\n\nThis project does regularly mention what commits a patch/commit fixes,\nbut that is done inline in the commit message proper (cf. the trailer\nblock of the message).\n\nFor `Link`: These are used both to link back to the patch submission as\nwell as with footnotes. In contrast this project has `refs/notes/amlog`\nfor linking back to the patch submissions, and footnotes are only used\nin the commit message proper.\n\n† 1: Commit linux/d5d6281a has “linux” in front of it since this commit\n is from the Linux Kernel, not Git. Example of a Linux tree—as well\n as an example of `Link`—is [2].\n\nLink: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/ [2]\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: Msg: it’s “cf.”, not “c.f.”\n\n Documentation/SubmittingPatches | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 4e8dea4eaa6..8d946e9acb3 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -476,6 +476,10 @@ While you can also create your own trailer if the situation warrants it, we\n encourage you to instead use one of the common trailers in this project\n highlighted above.\n \n+Other projects might regularly refer to other kinds of data, like\n+`Fixes:` and `Link:` in the Linux Kernel project, but these ones in\n+particular are not used in this project.\n+\n Only capitalize the very first letter of the trailer, i.e. favor\n \"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n \n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545915","messageId":"V3_Based-on-patch-by.9ef@msgid.xyz","threadId":"65789","inReplyTo":"V3_CV_SubPatches_trailers.9ec@msgid.xyz","subject":"[PATCH v3 3/5] SubmittingPatches: document Based-on-patch-by trailer","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-19T05:44:52Z","receivedAt":"2026-06-19T05:46:33Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis trailer comes up often enough and the use case is not fully covered\nby the other trailers here. For example, it is sometimes better to use\nthis trailer instead of `Co-authored-by:`.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Do *not* say *without sign-off*; do mention the precondition that\n it is signed off, and cover the case when the patch author did not\n sign off on it\n • https://lore.kernel.org/git/xmqqse6tnho1.fsf@gitster.g/\n • Drop “without a commit message”. It doesn’t seem important. A bare\n patch is just a patch, not a patch plus a message.\n\n Documentation/SubmittingPatches | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 8d946e9acb3..5b4ab93543c 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -465,6 +465,10 @@ These are the common trailers in use:\n and found it to have the desired effect.\n . `Co-authored-by:` is used to indicate that people exchanged drafts\n of a patch before submitting it.\n+. `Based-on-patch-by:` is used when someone else authored parts of the\n+ patch that you are submitting. This might be relevant if someone sent\n+ a patch to the mailing list with their sign-off. (Be mindful and ask\n+ them to sign off on it if they did not.)\n . `Helped-by:` is used to credit someone who suggested ideas for\n changes without providing the precise changes in patch form.\n . `Mentored-by:` is used to credit someone with helping develop a\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545916","messageId":"V3_just_trailer_markup.9f0@msgid.xyz","threadId":"65789","inReplyTo":"V3_CV_SubPatches_trailers.9ec@msgid.xyz","subject":"[PATCH v3 4/5] SubmittingPatches: be consistent with trailer markup","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-19T05:44:53Z","receivedAt":"2026-06-19T05:46:52Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThe rest of this section and (most importantly) the list has decided to\nuse `:`. So let’s use backticks (`) and a colon (:) throughout the\ndocument.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/SubmittingPatches | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 5b4ab93543c..125bc0a2d63 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -374,7 +374,7 @@ or, on an older version of Git without support for --pretty=reference:\n ....\n \n [[sign-off]]\n-=== Certify your work by adding your `Signed-off-by` trailer\n+=== Certify your work by adding your `Signed-off-by:` trailer\n \n To improve tracking of who did what, we ask you to certify that you\n wrote the patch or have the right to pass it on under the same license\n@@ -411,7 +411,7 @@ d. I understand and agree that this project and the contribution\n this project or the open source license(s) involved.\n ____\n \n-you add a \"Signed-off-by\" trailer to your commit, that looks like\n+you add a `Signed-off-by:` trailer to your commit, that looks like\n this:\n \n ....\n@@ -421,7 +421,7 @@ this:\n This line can be added by Git if you run the git-commit command with\n the -s option.\n \n-Notice that you can place your own `Signed-off-by` trailer when\n+Notice that you can place your own `Signed-off-by:` trailer when\n forwarding somebody else's patch with the above rules for\n D-C-O. Indeed you are encouraged to do so. Do not forget to\n place an in-body \"From: \" line at the beginning to properly attribute\n@@ -433,7 +433,7 @@ your patch differs from project to project, so it may be different\n from that of the project you are accustomed to.\n \n [[real-name]]\n-Please use a known identity in the `Signed-off-by` trailer, since we cannot\n+Please use a known identity in the `Signed-off-by:` trailer, since we cannot\n accept anonymous contributions. It is common, but not required, to use some form\n of your real name. We realize that some contributors are not comfortable doing\n so or prefer to contribute under a pseudonym or preferred name and we can accept\n@@ -485,7 +485,7 @@ Other projects might regularly refer to other kinds of data, like\n particular are not used in this project.\n \n Only capitalize the very first letter of the trailer, i.e. favor\n-\"Signed-off-by\" over \"Signed-Off-By\" and \"Acked-by:\" over \"Acked-By\".\n+`Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.\n \n [[ai]]\n === Use of Artificial Intelligence (AI)\n@@ -607,7 +607,7 @@ Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n how to submit updated versions of a patch series.\n \n If your log message (including your name on the\n-`Signed-off-by` trailer) is not writable in ASCII, make sure that\n+`Signed-off-by:` trailer) is not writable in ASCII, make sure that\n you send off a message in the correct encoding.\n \n WARNING: Be wary of your MUAs word-wrap\n@@ -627,7 +627,7 @@ previously sent.\n The `git format-patch` command follows the best current practice to\n format the body of an e-mail message. At the beginning of the\n patch should come your commit message, ending with the\n-`Signed-off-by` trailers, and a line that consists of three dashes,\n+`Signed-off-by:` trailers, and a line that consists of three dashes,\n followed by the diffstat information and the patch itself. If\n you are forwarding a patch from somebody else, optionally, at\n the beginning of the e-mail message just before the commit\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"545917","messageId":"V3_trailer_order_matters.9f1@msgid.xyz","threadId":"65789","inReplyTo":"V3_CV_SubPatches_trailers.9ec@msgid.xyz","subject":"[PATCH v3 5/5] SubmittingPatches: note that trailer order matters","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-19T05:44:54Z","receivedAt":"2026-06-19T05:47:11Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nIt matters where you put new trailers: they should be added in\nchronological order, and each person who passes on a patch should add\ntheir s-o-b last. You are signing off on the patch as well as the whole\nmessage up to that point.\n\nThis also makes it clear who added what:\n\n Acked-by: The Reviewer \n Signed-off-by: The Contributor \n Acked-by: The (Late) Reviewer \n Signed-off-by: The Maintainer \n\nThe first ack was added by the contributor and the second one was added\nby the maintainer.\n\nHelped-by: Junio C Hamano \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Mention this in both the DCO section (new) as well as the trailers\n section\n • Emphasize and lead with chronological order and let everything\n fall in place according to that\n • https://lore.kernel.org/git/xmqq8q8mt4eo.fsf@gitster.g/\n • Msg: Drop “the the”; one is enough\n\n Documentation/SubmittingPatches | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 125bc0a2d63..56706e55ea1 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -427,6 +427,10 @@ D-C-O. Indeed you are encouraged to do so. Do not forget to\n place an in-body \"From: \" line at the beginning to properly attribute\n the change to its true author (see (2) above).\n \n+Place this `Signed-off-by:` trailer at the end, after trailers added by\n+others and after other trailers added by you; see\n+<> below (\"chronological order\").\n+\n This procedure originally came from the Linux kernel project, so our\n rule is quite similar to theirs, but what exactly it means to sign-off\n your patch differs from project to project, so it may be different\n@@ -487,6 +491,12 @@ particular are not used in this project.\n Only capitalize the very first letter of the trailer, i.e. favor\n `Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`.\n \n+As mentioned under <> above, trailers are added in\n+chronological order; one person might sign-off on a patch and send it to\n+someone else, who then in turn adds her own sign-off. Further, any\n+trailers that you add beyond your sign-off should come before that\n+sign-off. That makes it clear what trailers which person added.\n+\n [[ai]]\n === Use of Artificial Intelligence (AI)\n \n-- \n2.54.0.22.g9e26862b904\n\n"}]}