[lmi] Proposal for commit references format in the commit messages

[Vadim Zeitlin]

 Hello again,

 So far, we've been referring to the existing commits in new commit
messages by their full SHA-1. This is completely unambiguous, but creates
word wrapping problems, due to the length of the commit hashes, and, maybe
more importantly, is not particularly clear, as baseline humans have little
capacity for remembering random sequences of 40 hexadecimal digits and so
it's impossible in practice to know which commit is being referred to
without using some Git command (git-log, git-show, ...) to look it up.

 Git project itself uses a different convention, as explained in the
"commit-reference" section of its patch submission guidelines at

https://git.kernel.org/pub/scm/git/git.git/plain/Documentation/SubmittingPatches?id=master

In brief, the commit reference should be in the format produced by "git
show -s --pretty=reference" command (or, if you prefer, the completely
equivalent "git log -1 --pretty=reference"). As also explained there, for
Git versions earlier than (very recent, as of time of this writing) 2.25,
which lack --pretty=reference support, this option can be replaced with a
more verbose "--date=short --pretty='format:%h (%s, %ad)'".

 In either case, the result can be seen in e.g. the commit message of

https://github.com/vadz/lmi/pull/139/commits/cc3412451592d715dc704a1f9309a3bcf6792f58

which I reproduce here:

    Remove unused starts_with() function from PDF generation code

    This function is not used any longer after the changes of the commit
    12f58cdd3 (Simplify single-premium conditionals, 2019-08-26) and
    resulted in -Wunused-function from clang.

 I believe this format of commit reference is much more useful than the
current one and I like it so much that I'm going to start using it for all
my other projects from now on.

 The only possible objection to it I can see is that commit SHA-1 which are
unique now might become ambiguous in the future. However in the
(relatively, but not completely) unlikely case that this happens we would
still be able to find the original commit by choosing the one with this
abbreviated SHA-1 before the specified date, so it should never be a
problem in practice.

 What do you think of using this format for lmi?
VZ

pgpNB7eTj4fLv.pgp
Description: PGP signature