From d0c6ecea230aed04ad703502b43c9b313ccfc95d Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Fri, 19 Jun 2026 07:44:50 +0200 Subject: [PATCH 1/5] SubmittingPatches: encourage trailer use for substantial help MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Trailers beyond the mandatory s-o-b are regularly used based on my last two years of reading the mailing list. Moreover, reviewers might encourage it.[1] This is also in line with the project crediting both commit authors and people mentioned in trailers each release; “Nobody is THE one making contribution”.[2] Adding trailers is already encouraged, but in the section `send-patches`. 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. Now we need to make a heading for `commit-trailers` in order for the HTML output to make sense. 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. Let’s also spell out that these trailers should follow the Git author/ committer format. One might naturally just write the name, but in that case it will not be picked up by: git shortlog --group=trailer: and normalization via `.mailmap` will not work. Also introduce the list of common trailers as such. Granted, this is already implied by the later paragraph about “create your own trailer”, so this just frontloads this information. † 1: https://lore.kernel.org/git/CAP8UFD0POvYDgGtEx8GBhvKkd8XzzWQsy8XxAKL9M3+uz3ka+w@mail.gmail.com/#:~:text=for%20at%20least † 2: https://lore.kernel.org/git/xmqqzh248sy0.fsf@gitster.c.googlers.com/ Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 176567738d..4e8dea4eaa 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -444,7 +444,15 @@ The goal of this policy is to allow us to have sufficient information to contact you if questions arise about your contribution. [[commit-trailers]] -If you like, you can put extra trailers at the end: +=== Commit trailers +It is polite to credit people who have helped with your work to a +substantial enough degree. This project uses commit trailers for that, +where the credited person is written out like a Git author, i.e. with +both their name and their email address. Note that the threshold to +credit someone is a judgement call, and crediting someone for simple +review work is certainly not necessary. + +These are the common trailers in use: . `Reported-by:` is used to credit someone who found the bug that the patch attempts to fix. @@ -562,8 +570,8 @@ when the maintainer did not heavily participate in the discussion and instead left the review to trusted others. Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and -`Tested-by:` lines as necessary to credit people who helped your -patch, and "cc:" them when sending such a final version for inclusion. +`Tested-by:` (see <>), and "cc:" them +when sending such a final version for inclusion. ==== `format-patch` and `send-email` From b7f68ff5c92e40157da2afeecba13bf6f4fdd6db Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Fri, 19 Jun 2026 07:44:51 +0200 Subject: [PATCH 2/5] SubmittingPatches: discourage common Linux trailers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Linux Kernel regularly uses trailers (or “tags”) `Fixes` and `Link`. Sometimes people submit patches to this project with them. They have their use in that project but it is not clear what purpose they would serve here. For `Fixes`: Linux has many trees, and applying patches with cherry-picks is common. A `Fixes` trailer in commit C2 pointing to commit C1 helps the cherry-picker figure out that she probably needs C2 if she wants to apply C1. See linux/d5d6281a (checkpatch: check for missing Fixes tags, 2024-06-11):[1] Why are stable patches encouraged to have a fixes tag? Some people mark their stable patches as "# 5.10" etc. This is useful but a Fixes tag is still a good idea. For example, the Fixes tag helps in review. It helps people to not cherry-pick buggy patches without also cherry-picking the fix. In contrast the Git project has few trees (to my knowledge), and there is much less need to cherry-pick fixes as opposed to either using backmerges or rebasing all of the downstream tree’s commits on top of 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 (cf. the trailer block of the message). For `Link`: These are used both to link back to the patch submission as well as with footnotes. In contrast this project has `refs/notes/amlog` for linking back to the patch submissions, and footnotes are only used in the commit message proper. † 1: Commit linux/d5d6281a has “linux” in front of it since this commit is from the Linux Kernel, not Git. Example of a Linux tree—as well as an example of `Link`—is [2]. Link: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/ [2] Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 4e8dea4eaa..8d946e9acb 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -476,6 +476,10 @@ 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 +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". From 6d2665156748bde12274cfb3aea24bca68d7ac0c Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Fri, 19 Jun 2026 07:44:52 +0200 Subject: [PATCH 3/5] SubmittingPatches: document Based-on-patch-by trailer This trailer comes up often enough and the use case is not fully covered by the other trailers here. For example, it is sometimes better to use this trailer instead of `Co-authored-by:`. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 8d946e9acb..5b4ab93543 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -465,6 +465,10 @@ These are the common trailers in use: and found it to have the desired effect. . `Co-authored-by:` is used to indicate that people exchanged drafts 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 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 From 89d86442441d354abddf53d06d440bc06500c738 Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Fri, 19 Jun 2026 07:44:53 +0200 Subject: [PATCH 4/5] SubmittingPatches: be consistent with trailer markup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The rest of this section and (most importantly) the list has decided to use `:`. So let’s use backticks (`) and a colon (:) throughout the document. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 5b4ab93543..125bc0a2d6 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -374,7 +374,7 @@ or, on an older version of Git without support for --pretty=reference: .... [[sign-off]] -=== Certify your work by adding your `Signed-off-by` trailer +=== Certify your work by adding your `Signed-off-by:` trailer To improve tracking of who did what, we ask you to certify that you wrote the patch or have the right to pass it on under the same license @@ -411,7 +411,7 @@ d. I understand and agree that this project and the contribution this project or the open source license(s) involved. ____ -you add a "Signed-off-by" trailer to your commit, that looks like +you add a `Signed-off-by:` trailer to your commit, that looks like this: .... @@ -421,7 +421,7 @@ this: This line can be added by Git if you run the git-commit command with the -s option. -Notice that you can place your own `Signed-off-by` trailer when +Notice that you can place your own `Signed-off-by:` trailer when forwarding somebody else's patch with the above rules for 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 @@ -433,7 +433,7 @@ your patch differs from project to project, so it may be different from that of the project you are accustomed to. [[real-name]] -Please use a known identity in the `Signed-off-by` trailer, since we cannot +Please use a known identity in the `Signed-off-by:` trailer, since we cannot accept anonymous contributions. It is common, but not required, to use some form of your real name. We realize that some contributors are not comfortable doing so or prefer to contribute under a pseudonym or preferred name and we can accept @@ -485,7 +485,7 @@ Other projects might regularly refer to other kinds of data, like particular are not used in this project. Only capitalize the very first letter of the trailer, i.e. favor -"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By". +`Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`. [[ai]] === Use of Artificial Intelligence (AI) @@ -607,7 +607,7 @@ Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on how to submit updated versions of a patch series. If your log message (including your name on the -`Signed-off-by` trailer) is not writable in ASCII, make sure that +`Signed-off-by:` trailer) is not writable in ASCII, make sure that you send off a message in the correct encoding. WARNING: Be wary of your MUAs word-wrap @@ -627,7 +627,7 @@ previously sent. The `git format-patch` command follows the best current practice to format the body of an e-mail message. At the beginning of the patch should come your commit message, ending with the -`Signed-off-by` trailers, and a line that consists of three dashes, +`Signed-off-by:` trailers, and a line that consists of three dashes, followed by the diffstat information and the patch itself. If you are forwarding a patch from somebody else, optionally, at the beginning of the e-mail message just before the commit From 55113123f5a830e5d4f1b728668a90a0e6ca7193 Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Fri, 19 Jun 2026 07:44:54 +0200 Subject: [PATCH 5/5] SubmittingPatches: note that trailer order matters 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: Acked-by: The Reviewer Signed-off-by: The Contributor Acked-by: The (Late) Reviewer Signed-off-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 Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 125bc0a2d6..56706e55ea 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 @@ -487,6 +491,12 @@ 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:`. +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)