[PATCH] CONTRIBUTING.d/: Document format of 'Fixes:' trailer fields
From: Alejandro Colomar <alx@kernel.org>
Date: 2026-02-03 20:25:56
Also in:
lkml
Subsystem:
the rest · Maintainer:
Linus Torvalds
Signed-off-by: Alejandro Colomar <alx@kernel.org> --- Hi! I hadn't yet documented how to produce the Fixes: trailer fields in the Linux man-pages project. We require the commit-date to disambiguate possible hash (and subject) collisions. This documents how to produce them easily. I hope this will be useful to other projects. I've been using this format for some time, and it has some nice properties: it shows at first glance the date of a commit (which itself gives an idea of how many stable versions would need to be fixed). It can also be parsed by a machine, by having a consistent and simple (unambiguous) format. Have a lovely night! Alex CONTRIBUTING.d/git | 16 ++++++++++++++++ CONTRIBUTING.d/patches/description | 11 +++++++++++ 2 files changed, 27 insertions(+)
diff --git a/CONTRIBUTING.d/git b/CONTRIBUTING.d/git
index 4b7a95472..3f944a23c 100644
--- a/CONTRIBUTING.d/git
+++ b/CONTRIBUTING.d/git@@ -43,6 +43,22 @@ Description $ git config --global \ sendemail.sendmailcmd 'mutt -H - && true'; + Commit references + 'Fixes:' trailer fields should have the following format. + + Fixes: 12-char-hash ([author-date,] commit-date; "subject") + + where the author date is optional, and only included if it's + somehow important. The commit date is often more important, as + it's sorted, and thus can be used to find (with a binary search) + a commit whose hash and subject may have collisions. To produce + such fields, the following git aliases are useful. + + $ git config --global alias.ref \ + "show --no-patch --abbrev=12 --date=short --format=tformat:'%C(auto)%h%C(reset) %C(dim white)(%cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(dim white)\")%C(reset)'" + $ git config --global alias.ref2 \ + "show --no-patch --abbrev=12 --date=short --format=tformat:'%C(auto)%h%C(reset) %C(dim white)(%ad, %cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(dim white)\")%C(reset)'" + See also git-config(1) git-diff(1)
diff --git a/CONTRIBUTING.d/patches/description b/CONTRIBUTING.d/patches/description
index 73b603bf3..09ee35ec8 100644
--- a/CONTRIBUTING.d/patches/description
+++ b/CONTRIBUTING.d/patches/description@@ -55,3 +55,14 @@ Description "Co-developed-by:". Example: Signed-off-by: Alejandro Colomar <alx@kernel.org> + + Add 'Fixes:' tags as necessary. See <CONTRIBUTING.d/git> for + how to configure the alias.ref and alias.ref2 git aliases. The + commit references can be produced with them. + + $ git ref bb509e6fc + bb509e6fcbae (2020-10-16; "kernel_lockdown.7: New page documenting the Kernel Lockdown feature") + + which then can be used as + + Fixes: bb509e6fcbae (2020-10-16; "kernel_lockdown.7: New page documenting the Kernel Lockdown feature")
Range-diff: -: --------- > 1: 3a656e903 CONTRIBUTING.d/: Document format of 'Fixes:' trailer fields base-commit: be29e611a386b754fd5ce9f9d1ef421d15319ec1 -- 2.51.0