CONTRIBUTING.adoc: document how to refer to a commit in commit messages

This is what I already do, I would like it to make it an official
procedure.  What I want to avoid is having commits referred to just
using their hashes, which is meaningless for humans.

Change-Id: I47b5044d74d3d10e2b953fe7ad291b4468391da2
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Reviewed-on: https://review.lttng.org/c/babeltrace/+/13379
Reviewed-by: Philippe Proulx <eeppeliteloop@gmail.com>

diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index 9225518b96d5f47fbe849c59a7ba9ee550776572..c15dc1cea042a5e23fc70291b966564d119a87a3 100644 (file)
--- a/CONTRIBUTING.adoc
+++ b/CONTRIBUTING.adoc
@@ -1,8 +1,8 @@
 // Render with Asciidoctor
 
 = Babeltrace{nbsp}2 contributor's guide
-Jérémie Galarneau, Philippe Proulx
-22 February 2024
+Jérémie Galarneau, Simon Marchi, Philippe Proulx
+23 October 2024
 :toc: left
 :toclevels: 3
 :icons: font
@@ -2307,3 +2307,19 @@ https://github.com/psf/black[Black] specified in `dev-requirements.txt`.
 
 All Python imports must be sorted using the version of
 https://pycqa.github.io/isort/[isort] indicated in `dev-requirements.txt`.
+
+== Git
+
+=== Commit message style
+
+When referring to a specific commit (either in free text or in a
+trailer line), use the `__12-DIGIT HASH__ ("__SUBJECT__")`
+https://www.kernel.org/doc/html/v4.10/process/submitting-patches.html#describe-your-changes[format],
+for example:
+
+    602446e40e7a ("ctf: add explicit cast to CStringView in ternary")
+
+Generate such a string from the `HEAD` commit of a repository with:
+
+    $ git log -1 --abbrev=12 --pretty='%h ("%s")'
+