CONTRIBUTING.d/: Document format of 'Fixes:' trailer fields

Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/CONTRIBUTING.d/git b/CONTRIBUTING.d/git
index 4b7a95472b46e82116fce801e2bd5d14d99d7c2c..3b301c7f4d75721e47e9643206a5d5bc365741fa 100644 (file)
--- a/CONTRIBUTING.d/git
+++ b/CONTRIBUTING.d/git
@@ -43,6 +43,15 @@ Description
                $ git config --global \
                        sendemail.sendmailcmd 'mutt -H - && true';
 
+    alias.ref, alias.ref2
+       To produce git commit references, the following git aliases are
+       useful.
+
+               $ git config --global alias.ref \
+                       "show -s --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 -s --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/trailer b/CONTRIBUTING.d/patches/trailer
index 51950f5bba33ecf4a2a49ff6cacbe862df367c07..c04440516ae22a5767a2a4d3b577a1a45c56a3d9 100644 (file)
--- a/CONTRIBUTING.d/patches/trailer
+++ b/CONTRIBUTING.d/patches/trailer
@@ -12,3 +12,24 @@ Description
        "Co-developed-by:".  Example:
 
                Signed-off-by: Alejandro Colomar <alx@kernel.org>
+
+    Fixes
+       Add 'Fixes:' tags as necessary.  '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.  For
+       example:
+
+               Fixes: bb509e6fcbae (2020-10-16; "kernel_lockdown.7: New page documenting the Kernel Lockdown feature")
+
+       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")