build(hooks): add Husky configuration

Husky is a tool for managing Git hooks within the repository itself.
Traditionally, commit hooks need to be manually installed on a per-user
basis, but Husky allows us to install these hooks either automatically
when `npm install` is invoked within the repository, or manually with
`npx husky install`.

This will become useful for us in the next few patches when we begin
introducing tools for enforcing a commit message style.

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

5 files changed, 98 insertions, 10 deletions

diff --git a/.gitignore b/.gitignore
index 79c510405..f52465811 100644
--- a/.gitignore
+++ b/.gitignore
@@ -42,3 +42,5 @@ GTAGS
 # Ctags
 tags
 
+# Node.js
+node_modules/
diff --git a/.husky/.gitignore b/.husky/.gitignore
new file mode 100644
index 000000000..31354ec13
--- /dev/null
+++ b/.husky/.gitignore
@@ -0,0 +1 @@
+_
diff --git a/docs/getting_started/prerequisites.rst b/docs/getting_started/prerequisites.rst
index e2c527e72..9c65c6056 100644
--- a/docs/getting_started/prerequisites.rst
+++ b/docs/getting_started/prerequisites.rst
@@ -75,6 +75,12 @@ These tools are optional:
    The standard software package used for debugging software on Arm development
    platforms and |FVP| models.
 
+- Node.js >= 14
+
+   Highly recommended, and necessary in order to install and use the packaged
+   Git hooks and helper tools. Without these tools you will need to rely on the
+   CI for feedback on commit message conformance.
+
 Package Installation (Linux)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -91,6 +97,17 @@ The optional packages can be installed using:
 
     sudo apt install device-tree-compiler
 
+Additionally, to install an up-to-date version of Node.js, you can use the `Node
+Version Manager`_ to install a version of your choosing (we recommend 14, but
+later LTS versions might offer a more stable experience):
+
+.. code:: shell
+
+    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | "$SHELL"
+    exec "$SHELL" -ic "nvm install 14; exec $SHELL"
+
+.. _Node Version Manager: https://github.com/nvm-sh/nvm#install--update-script
+
 Supporting Files
 ----------------
 
@@ -109,27 +126,43 @@ in your shell:
 
 .. code:: shell
 
-    git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a" && (cd "trusted-firmware-a" && mkdir -p .git/hooks && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg; chmod +x `git rev-parse --git-dir`/hooks/commit-msg)
+    git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a"
 
-This will clone the Git repository also install a *commit hook* that
-automatically inserts appropriate *Change-Id:* lines at the end of your
-commit messages. These change IDs are required when committing changes that you
-intend to push for review via our Gerrit system.
+Additional Steps for Contributors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can read more about Git hooks in the *githooks* page of the Git documentation,
-available at: https://git-scm.com/docs/githooks
+If you are planning on contributing back to TF-A, there are some things you'll
+want to know.
 
-Alternatively, you can clone without the commit hook using:
+TF-A is hosted by a `Gerrit Code Review`_ server. Gerrit requires that all
+commits include a ``Change-Id`` footer, and this footer is typically
+automatically generated by a Git hook installed by you, the developer.
+
+If you have Node.js installed already, you can automatically install this hook,
+along with any additional hooks and Javascript-based tooling that we use, by
+running from within your newly-cloned repository:
 
 .. code:: shell
 
-    git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a"
+    npm install
+
+If you have opted **not** to install Node.js, you can install the Gerrit hook
+manually by running:
+
+.. code:: shell
+
+    curl -Lo $(git rev-parse --git-dir)/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg
+    chmod +x $(git rev-parse --git-dir)/hooks/commit-msg
+
+You can read more about Git hooks in the *githooks* page of the Git
+documentation, available `here <https://git-scm.com/docs/githooks>`_.
 
 --------------
 
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
 
 .. _Arm Developer website: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads
+.. _Gerrit Code Review: https://www.gerritcodereview.com/
 .. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes
 .. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables
 .. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio
diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 000000000..a7f581073
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,43 @@
+{
+  "name": "tf-a",
+  "lockfileVersion": 2,
+  "requires": true,
+  "packages": {
+    "": {
+      "hasInstallScript": true,
+      "devDependencies": {
+        "husky": "^5.0.4"
+      }
+    },
+    "node_modules/husky": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/husky/-/husky-5.2.0.tgz",
+      "integrity": "sha512-AM8T/auHXRBxlrfPVLKP6jt49GCM2Zz47m8G3FOMsLmTv8Dj/fKVWE0Rh2d4Qrvmy131xEsdQnb3OXRib67PGg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/typicode"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/husky"
+        }
+      ],
+      "bin": {
+        "husky": "lib/bin.js"
+      },
+      "engines": {
+        "node": ">= 10"
+      }
+    }
+  },
+  "dependencies": {
+    "husky": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/husky/-/husky-5.2.0.tgz",
+      "integrity": "sha512-AM8T/auHXRBxlrfPVLKP6jt49GCM2Zz47m8G3FOMsLmTv8Dj/fKVWE0Rh2d4Qrvmy131xEsdQnb3OXRib67PGg==",
+      "dev": true
+    }
+  }
+}
diff --git a/package.json b/package.json
new file mode 100644
index 000000000..a11a1ed2d
--- /dev/null
+++ b/package.json
@@ -0,0 +1,9 @@
+{
+  "private": true,
+  "scripts": {
+    "postinstall": "husky install"
+  },
+  "devDependencies": {
+    "husky": "^5.0.4"
+  }
+}