Merge changes from topic "ck/conventional-commits" into integration

* changes:
  build(hooks): add commitlint hook
  build(hooks): add Commitizen hook
  build(hooks): add Gerrit hook
  build(hooks): add Husky configuration

.cz.json

@@ -0,0 +1,5 @@
+{
+    "path": "./node_modules/cz-conventional-changelog",
+    "maxHeaderWidth": 50,
+    "maxLineWidth": 72
+}

.gitignore

@@ -42,3 +42,5 @@ GTAGS
 # Ctags
 tags
 
+# Node.js
+node_modules/

.husky/.gitignore

@@ -0,0 +1 @@
+_

.husky/commit-msg

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+# shellcheck source=./_/husky.sh
+. "$(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"

.husky/commit-msg.gerrit

@@ -0,0 +1,194 @@
+#!/bin/sh
+# From Gerrit Code Review 2.14.20
+#
+# Part of Gerrit Code Review (https://www.gerritcodereview.com/)
+#
+# Copyright (C) 2009 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+unset GREP_OPTIONS
+
+CHANGE_ID_AFTER="Bug|Depends-On|Issue|Test|Feature|Fixes|Fixed"
+MSG="$1"
+
+# Check for, and add if missing, a unique Change-Id
+#
+add_ChangeId() {
+	clean_message=`sed -e '
+		/^diff --git .*/{
+			s///
+			q
+		}
+		/^Signed-off-by:/d
+		/^#/d
+	' "$MSG" | git stripspace`
+	if test -z "$clean_message"
+	then
+		return
+	fi
+
+	# Do not add Change-Id to temp commits
+	if echo "$clean_message" | head -1 | grep -q '^\(fixup\|squash\)!'
+	then
+		return
+	fi
+
+	if test "false" = "`git config --bool --get gerrit.createChangeId`"
+	then
+		return
+	fi
+
+	# Does Change-Id: already exist? if so, exit (no change).
+	if grep -i '^Change-Id:' "$MSG" >/dev/null
+	then
+		return
+	fi
+
+	id=`_gen_ChangeId`
+	T="$MSG.tmp.$$"
+	AWK=awk
+	if [ -x /usr/xpg4/bin/awk ]; then
+		# Solaris AWK is just too broken
+		AWK=/usr/xpg4/bin/awk
+	fi
+
+	# Get core.commentChar from git config or use default symbol
+	commentChar=`git config --get core.commentChar`
+	commentChar=${commentChar:-#}
+
+	# How this works:
+	# - parse the commit message as (textLine+ blankLine*)*
+	# - assume textLine+ to be a footer until proven otherwise
+	# - exception: the first block is not footer (as it is the title)
+	# - read textLine+ into a variable
+	# - then count blankLines
+	# - once the next textLine appears, print textLine+ blankLine* as these
+	#   aren't footer
+	# - in END, the last textLine+ block is available for footer parsing
+	$AWK '
+	BEGIN {
+		if (match(ENVIRON["OS"], "Windows")) {
+			RS="\r?\n" # Required on recent Cygwin
+		}
+		# while we start with the assumption that textLine+
+		# is a footer, the first block is not.
+		isFooter = 0
+		footerComment = 0
+		blankLines = 0
+	}
+
+	# Skip lines starting with commentChar without any spaces before it.
+	/^'"$commentChar"'/ { next }
+
+	# Skip the line starting with the diff command and everything after it,
+	# up to the end of the file, assuming it is only patch data.
+	# If more than one line before the diff was empty, strip all but one.
+	/^diff --git / {
+		blankLines = 0
+		while (getline) { }
+		next
+	}
+
+	# Count blank lines outside footer comments
+	/^$/ && (footerComment == 0) {
+		blankLines++
+		next
+	}
+
+	# Catch footer comment
+	/^\[[a-zA-Z0-9-]+:/ && (isFooter == 1) {
+		footerComment = 1
+	}
+
+	/]$/ && (footerComment == 1) {
+		footerComment = 2
+	}
+
+	# We have a non-blank line after blank lines. Handle this.
+	(blankLines > 0) {
+		print lines
+		for (i = 0; i < blankLines; i++) {
+			print ""
+		}
+
+		lines = ""
+		blankLines = 0
+		isFooter = 1
+		footerComment = 0
+	}
+
+	# Detect that the current block is not the footer
+	(footerComment == 0) && (!/^\[?[a-zA-Z0-9-]+:/ || /^[a-zA-Z0-9-]+:\/\//) {
+		isFooter = 0
+	}
+
+	{
+		# We need this information about the current last comment line
+		if (footerComment == 2) {
+			footerComment = 0
+		}
+		if (lines != "") {
+			lines = lines "\n";
+		}
+		lines = lines $0
+	}
+
+	# Footer handling:
+	# If the last block is considered a footer, splice in the Change-Id at the
+	# right place.
+	# Look for the right place to inject Change-Id by considering
+	# CHANGE_ID_AFTER. Keys listed in it (case insensitive) come first,
+	# then Change-Id, then everything else (eg. Signed-off-by:).
+	#
+	# Otherwise just print the last block, a new line and the Change-Id as a
+	# block of its own.
+	END {
+		unprinted = 1
+		if (isFooter == 0) {
+			print lines "\n"
+			lines = ""
+		}
+		changeIdAfter = "^(" tolower("'"$CHANGE_ID_AFTER"'") "):"
+		numlines = split(lines, footer, "\n")
+		for (line = 1; line <= numlines; line++) {
+			if (unprinted && match(tolower(footer[line]), changeIdAfter) != 1) {
+				unprinted = 0
+				print "Change-Id: I'"$id"'"
+			}
+			print footer[line]
+		}
+		if (unprinted) {
+			print "Change-Id: I'"$id"'"
+		}
+	}' "$MSG" > "$T" && mv "$T" "$MSG" || rm -f "$T"
+}
+_gen_ChangeIdInput() {
+	echo "tree `git write-tree`"
+	if parent=`git rev-parse "HEAD^0" 2>/dev/null`
+	then
+		echo "parent $parent"
+	fi
+	echo "author `git var GIT_AUTHOR_IDENT`"
+	echo "committer `git var GIT_COMMITTER_IDENT`"
+	echo
+	printf '%s' "$clean_message"
+}
+_gen_ChangeId() {
+	_gen_ChangeIdInput |
+	git hash-object -t commit --stdin
+}
+
+
+add_ChangeId

.husky/prepare-commit-msg

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+# shellcheck source=./_/husky.sh
+. "$(dirname "$0")/_/husky.sh"
+
+"$(dirname "$0")/prepare-commit-msg.cz" "$@"

.husky/prepare-commit-msg.cz

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+file="$1"
+type="$2"
+
+if [ -z "$type" ]; then # only run on new commits
+    #
+    # Save any commit message trailers generated by Git.
+    #
+
+    trailers=$(git interpret-trailers --parse "$file")
+
+    #
+    # Execute the Commitizen hook.
+    #
+
+    (exec < "/dev/tty" && npx --no-install git-cz --hook) || true
+
+    #
+    # Restore any trailers that Commitizen might have overwritten.
+    #
+
+    printf "\n" >> "$file"
+
+    while IFS= read -r trailer; do
+        git interpret-trailers --in-place --trailer "$trailer" "$file"
+    done <<< "$trailers"
+fi

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/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
+Additional Steps for Contributors
-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.
 
-You can read more about Git hooks in the *githooks* page of the Git documentation,
+If you are planning on contributing back to TF-A, there are some things you'll
-available at: https://git-scm.com/docs/githooks
+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

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/

package.json

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "scripts": {
+    "postinstall": "husky install"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^11.0.0",
+    "@commitlint/config-conventional": "^11.0.0",
+    "commitizen": "^4.2.2",
+    "cz-conventional-changelog": "^3.3.0",
+    "husky": "^5.0.4"
+  }
+}