git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v3 1/5] SubmittingPatches: encourage trailer use for substantial help

From
Kkristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
Date
Jun 19, 2026, 05:44 UTC
Message-ID
<V3_encourage_substantial.9ed@msgid.xyz>
In-Reply-To
<V3_CV_SubPatches_trailers.9ec@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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:<key>
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 <code@khaugsbakk.name>
---
Notes (series):
    v3: correct anchor placement
        🔗 https://lore.kernel.org/git/xmqq4ij0vo8f.fsf@gitster.g/
    v2:
    • Msg: proofreading typos, dropped words[1]
    • Msg: Avoid hyphenating for linebreaks on syllable[1]
    🔗 1: https://lore.kernel.org/git/310ef65e-b6c7-4d0c-a58a-0c88257143ba@app.fastmail.com/
 Documentation/SubmittingPatches | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 176567738d4..4e8dea4eaa6 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 <<commit-trailers,Commit trailers>>), and "cc:" them
+when sending such a final version for inclusion.
 
 ==== `format-patch` and `send-email`
 
-- 
2.54.0.22.g9e26862b904
Previous: kristofferhaugsbakk@fastmail.comNext: kristofferhaugsbakk@fastmail.com
Message 28 of 32 in “SubmittingPatches: update and flesh out trailer sections”
  1. 0/6 SubmittingPatches: update and flesh out trailer sectionskristofferhaugsbakk@fastmail.com, Jun 10, 2026
  2. 1/6 SubmittingPatches: encourage trailer use for substantial helpkristofferhaugsbakk@fastmail.com, Jun 10, 2026
  3. Junio C HamanoJun 11, 2026
  4. Kristoffer HaugsbakkJun 16, 2026
  5. 2/6 SubmittingPatches: discuss non-ident trailerskristofferhaugsbakk@fastmail.com, Jun 10, 2026
  6. Patrick SteinhardtJun 12, 2026
  7. Kristoffer HaugsbakkJun 16, 2026
  8. Patrick SteinhardtJun 17, 2026
  9. Kristoffer HaugsbakkJun 17, 2026
  10. 3/6 SubmittingPatches: discourage common Linux trailerskristofferhaugsbakk@fastmail.com, Jun 10, 2026
  11. Junio C HamanoJun 11, 2026
  12. 4/6 SubmittingPatches: document Based-on-patch-by trailerkristofferhaugsbakk@fastmail.com, Jun 10, 2026
  13. Junio C HamanoJun 11, 2026
  14. Kristoffer HaugsbakkJun 16, 2026
  15. 5/6 SubmittingPatches: be consistent with trailer markupkristofferhaugsbakk@fastmail.com, Jun 10, 2026
  16. 6/6 SubmittingPatches: note that trailer order matterskristofferhaugsbakk@fastmail.com, Jun 10, 2026
  17. Junio C HamanoJun 10, 2026
  18. Kristoffer HaugsbakkJun 16, 2026
  19. 0/5 SubmittingPatches: update and flesh out trailer sectionskristofferhaugsbakk@fastmail.com, Jun 17, 2026
  20. 1/5 SubmittingPatches: encourage trailer use for substantial helpkristofferhaugsbakk@fastmail.com, Jun 17, 2026
  21. Junio C HamanoJun 17, 2026
  22. Kristoffer HaugsbakkJun 18, 2026
  23. 2/5 SubmittingPatches: discourage common Linux trailerskristofferhaugsbakk@fastmail.com, Jun 17, 2026
  24. 3/5 SubmittingPatches: document Based-on-patch-by trailerkristofferhaugsbakk@fastmail.com, Jun 17, 2026
  25. 4/5 SubmittingPatches: be consistent with trailer markupkristofferhaugsbakk@fastmail.com, Jun 17, 2026
  26. 5/5 SubmittingPatches: note that trailer order matterskristofferhaugsbakk@fastmail.com, Jun 17, 2026
  27. 0/5 SubmittingPatches: update and flesh out trailer sectionskristofferhaugsbakk@fastmail.com, Jun 19, 2026
  28. 1/5 SubmittingPatches: encourage trailer use for substantial helpkristofferhaugsbakk@fastmail.com, Jun 19, 2026
  29. 2/5 SubmittingPatches: discourage common Linux trailerskristofferhaugsbakk@fastmail.com, Jun 19, 2026
  30. 3/5 SubmittingPatches: document Based-on-patch-by trailerkristofferhaugsbakk@fastmail.com, Jun 19, 2026
  31. 4/5 SubmittingPatches: be consistent with trailer markupkristofferhaugsbakk@fastmail.com, Jun 19, 2026
  32. 5/5 SubmittingPatches: note that trailer order matterskristofferhaugsbakk@fastmail.com, Jun 19, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.