build(hooks): add commitlint hook

This change adds a configuration for commitlint - a tool designed to
enforce a particular commit message style - and run it as part of Git's
commit-msg hook. This validates commits immediately after the editor has
been exited, and the configuration is derived from the configuration we
provide to Commitizen.

While the configuration provided suggests a maximum header and body
length, neither of these are hard errors. This is to accommodate the
occasional commit where it may be difficult or impossible to comply
with the length requirements (for example, with a particularly long
scope, or a long URL in the message body).

Change-Id: Ib5e90472fd1f1da9c2bff47703c9682232ee5679
Signed-off-by: Chris Kay <chris.kay@arm.com>

.husky/commit-msg

@@ -4,3 +4,4 @@
 . "$(dirname "$0")/_/husky.sh"
 
 "$(dirname "$0")/commit-msg.gerrit" "$@"
+"$(dirname "$0")/commit-msg.commitlint" "$@"

.husky/commit-msg.commitlint

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+npx --no-install commitlint --edit "$1"

commitlint.config.js

@@ -0,0 +1,14 @@
+/* eslint-env node */
+
+"use strict";
+
+const config = require("./.cz.json");
+
+module.exports = {
+    extends: ["@commitlint/config-conventional"],
+    rules: {
+        "header-max-length": [1, "always", config.maxHeaderWidth], /* Warning */
+        "body-max-line-length": [1, "always", config.maxLineWidth], /* Warning */
+        "signed-off-by": [2, "always", "Signed-off-by:"] /* Error */
+    }
+};

docs/process/contributing.rst

@@ -29,6 +29,20 @@ Making Changes
 -  Make commits of logical units. See these general `Git guidelines`_ for
    contributing to a project.
 
+-  Ensure your commit messages comply with the `Conventional Commits`_
+   specification:
+
+   .. code::
+
+       <type>[optional scope]: <description>
+
+       [optional body]
+
+       [optional footer(s)]
+
+   You can use the tooling installed by the optional steps in the
+   :ref:`prerequisites <Prerequisites>` guide to validate this locally.
+
 -  Keep the commits on topic. If you need to fix another bug or make another
    enhancement, please address it on a separate topic branch.
 
@@ -216,6 +230,7 @@ Binary Components
 
 *Copyright (c) 2013-2020, Arm Limited and Contributors. All rights reserved.*
 
+.. _Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0
 .. _developer.trustedfirmware.org: https://developer.trustedfirmware.org
 .. _review.trustedfirmware.org: https://review.trustedfirmware.org
 .. _issue: https://developer.trustedfirmware.org/project/board/1/