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

[Alejandro Colomar <alx@kernel.org>]

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