From 939dc9a58c5667ea18809c3a5e97ef1b60eb746c Mon Sep 17 00:00:00 2001
From: Ben Boeckel <ben.boeckel@kitware.com>
Date: Thu, 24 Jan 2019 13:31:37 -0500
Subject: Help: prefer commit hashes in commit references

The logic is that the describe output is readily available using `git
tag --contains` locally. In addition, for a hypothetical commit which
landed in both v3.9.4 and v3.10.1, there is no "better" tag to refer to.
since v3.10.0's relation to such a commit is unclear either way.

Also mention that a `Fixes` trailer is preferred if the mention is just
to indicate a commit which introduced an error rather than writing a
complete sentence about it.
---
 Help/dev/review.rst | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/Help/dev/review.rst b/Help/dev/review.rst
index 0c4eded..1d664c4 100644
--- a/Help/dev/review.rst
+++ b/Help/dev/review.rst
@@ -238,12 +238,10 @@ Referencing Commits in Commit Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The preferred form for references to other commits is
-``commit <commit> (<subject>, <date>)``, where:
+``commit <shorthash> (<subject>, <date>)``, where:
 
-* ``<commit>``:
-  If available, a tag-relative name of the commit produced by
-  ``git describe --contains <commit-ish>``.  Otherwise, the first
-  8-10 characters of the commit ``<hash>``.
+* ``<shorthash>``:
+  The abbreviated hash of the commit.
 
 * ``<subject>``:
   The first line of the commit message.
@@ -252,6 +250,17 @@ The preferred form for references to other commits is
   The author date of the commit, in its original time zone, formatted as
   ``CCYY-MM-DD``.  ``git-log(1)`` shows the original time zone by default.
 
+This may be generated with
+``git show -s --date=short --pretty="format:%h (%s, %ad)" <commit>``.
+
+If the commit is a fix for the mentioned commit, consider using a ``Fixes:``
+trailer in the commit message with the specified format. This trailer should
+not be word-wrapped. Note that if there is also an issue for what is being
+fixed, it is preferrable to link to the issue instead.
+
+If relevant, add the first release tag of CMake containing the commit after
+the ``<date>``, i.e., ``commit <shorthash> (<subject>, <date>, <tag>)``.
+
 Alternatively, the full commit ``<hash>`` may be used.
 
 Revising Commit Messages
-- 
cgit v0.12