gh-3106 CONTRIBUTORS file updated to reflect requirement for issue ref.

Generating changelogs and generally tracking progress on builds (and working
around githib shortcomings) is going to be a lot easier if we get stricter
about the formatting of commit messages.

Reword the CONTRIBUTORS file to make the use of a github issue reference a
requirement rather than a guideline, and provide git hooks to allow easy
checking.

Fixes gh-3106.

Signed-off-by: Richard Chapman <rchapman@hpccsystems.com>

CONTRIBUTORS

@@ -127,7 +127,7 @@ to fulfill the following requirements:
     to review it for them).
 5.  The code should compile, without warnings, on all supported targets.
 6.  If appropriate, new tests must accompany new functionality.
-7.  The commit messages should conform to the commit message guidelines described below
+7.  The commit messages must conform to the commit message guidelines described below
 8.  The commits in the branch should progress logically and forwards. If you started
     coding something one way, then changed your mind and coded it a different way, use
     git rebase -i to squash commits together so that the reviewer doesn't have to
@@ -158,13 +158,14 @@ Commit messages
 
 We follow the same guidelines that many other git projects have adopted for git comments.
 
-1.  The first line of the commit should summarize the change in no more than 50(ish)
-    characters. Start with a capital, do not end with a full stop. If the commit refers
-    to an open issue then start the comment with gh-NNN.
+1.  The first line of the commit must start gh-NNN where NNN is the github issue that the
+    commit is adddressing. This should be followed by a space, then a short summary of the
+    change (this will appear in the condensed form of the changelog generated from the
+    git history). Start with a capital, do not end with a full stop.
 
 2.  The second line of the commit message should be blank
 
-3.  The remainder of the commit message should be wrapped at 75 chars, and should contain
+3.  The remainder of the commit message should be wrapped at 80 chars, and should contain
     the following information (where appropriate):
 
       - what the behaviour was before this change.
@@ -180,4 +181,11 @@ We follow the same guidelines that many other git projects have adopted for git
     should say "Add O(n) travelling salesman support" rather than "Adds fast TSP", "Added
     code to make system faster", or "I changed line 32".
 
-4.  The commit message must be signed. Use commit -s to make this easier.
+4.  If the commit is a complete fix for the github issue referenced in the summary line,
+    you can add a line "Fixes gh-NNNN." at the bottom of the commit message.
+
+5.  The commit message must be signed. Use commit -s to make this easier.
+
+If you copy the files from the githooks directory into .git/hooks, then git will automatically
+check (some of) these requirements whenevery you commit. This is strongly encouraged to
+ensure that we can accept commits promptly.

githooks/commit-msg

@@ -0,0 +1,33 @@
+#!/bin/sh
+#
+# Every commit should have an issue reference at the start of the first line:
+
+(head -1 "$1" | grep -E -q "^gh-[0-9]+ ") || {
+  echo >&2 "Missing GitHub issue"
+  echo >&2 ""
+  echo >&2 "Please see the guidelines for git commit messages in the CONTRIBUTORS file"
+  echo >&2 "Your git commit message should start with a line of the form"
+  echo >&2 ""
+  echo >&2 "gh-XXXX short description"
+  echo >&2 ""
+  echo >&2 "where XXXX is the github issue number that this commit is referencing, and"
+  echo >&2 "short description is a brief description of the issue that will appear in"
+  echo >&2 "the --oneline version of the generated changelog."
+  exit 1
+}
+
+[ $(cat "$1" | wc -L ) -le 80 ] || {
+  echo >&2 "Commit message lines too long."
+  echo >&2 ""
+  echo >&2 "Please see the guidelines for git commit messages in the CONTRIBUTORS file."
+  echo >&2 "Lines in the commit message should be no longer than 80 characters."
+  exit 1
+}
+
+(grep -q "^Signed-off-by: " "$1") || {
+  echo >&2 "Commit not signed."
+  echo >&2 ""
+  echo >&2 "Please see the guidelines for git commit messages in the CONTRIBUTORS file."
+  echo >&2 "All commits should be signed (use git commit -s)."
+  exit 1
+}

githooks/pre-commit

@@ -0,0 +1,46 @@
+#!/bin/sh
+#
+# An example hook script to verify what is about to be committed.
+# Called by "git commit" with no arguments.  The hook should
+# exit with non-zero status after issuing an appropriate message if
+# it wants to stop the commit.
+#
+# To enable this hook, rename this file to "pre-commit".
+
+if git rev-parse --verify HEAD >/dev/null 2>&1
+then
+  against=HEAD
+else
+  # Initial commit: diff against an empty tree object
+  against=4b825dc642cb6eb9a060e54bf8d69288fbee4904
+fi
+
+# If you want to allow non-ascii filenames set this variable to true.
+allownonascii=$(git config hooks.allownonascii)
+
+# Cross platform projects tend to avoid non-ascii filenames; prevent
+# them from being added to the repository. We exploit the fact that the
+# printable range starts at the space character and ends with tilde.
+if [ "$allownonascii" != "true" ] &&
+  # Note that the use of brackets around a tr range is ok here, (it's
+  # even required, for portability to Solaris 10's /usr/bin/tr), since
+  # the square bracket bytes happen to fall in the designated range.
+  test "$(git diff --cached --name-only --diff-filter=A -z $against |
+        LC_ALL=C tr -d '[ -~]\0')"
+then
+  echo "Error: Attempt to add a non-ascii file name."
+  echo
+  echo "This can cause problems if you want to work"
+  echo "with people on other platforms."
+  echo
+  echo "To be portable it is advisable to rename the file ..."
+  echo
+  echo "If you know what you are doing you can disable this"
+  echo "check using:"
+  echo
+  echo "  git config hooks.allownonascii true"
+  echo
+  exit 1
+fi
+
+exec git diff-index --check --cached $against --