From 9204575d5ec5735c69a511b2c92eb12efb21379b Mon Sep 17 00:00:00 2001
From: Eric James Michael Ritz <ejmr@no.current.address>
Date: Fri, 27 Jul 2018 21:19:18 -0400
Subject: [PATCH] Add a default Git commit template message

Git allows users to have "templates" for commits which, when they
exist, automatically fill the user's editor with the template contents
whenever they make a commit.  This does not prevent the user from
further editing the commit message; all it does is pre-populate the
message with pre-written text.

In an effort to help improve the quality of commit messages on PHP
Mode, this patch introduces a commit template along with a Git hook
that, when applied, will automatically fill commit messages with
said template.  The template has comments describing some basic
best-practices for writing Git messages, and has commented-out lines
of some metadata we use, i.e. lines like

	GitHub-Issue: #9001
	Reviewed-by: Vegeta

This patch updates the Makefile with a new rule, `dev`, that will
install the hook.  However, developers have another way to use the
template, which will be necessary for anyone who happens to already
be using the `prepare-commit-msg` hook for something: users can open
`.git/config` in the project's top-level directory (tip: `git rev-parse
--show-toplevel`) and add the following:

	[commit]
		template = ./etc/git/commit-template.txt

This will apply the commit template for *every* commit.  In contrast,
the hook will only use the template if it can determine the user does
not already have a template in place or that a different tool has
pre-populated the commit message with some text.  So in that regard
the two approachs to using the template are different.

Signed-off-by: Eric James Michael Ritz <ejmr@no.current.address>
---
 Makefile                    |  6 ++++++
 etc/git/commit-template.txt | 13 +++++++++++++
 etc/git/prepare-commit-msg  | 35 +++++++++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+)
 create mode 100644 etc/git/commit-template.txt
 create mode 100755 etc/git/prepare-commit-msg

diff --git a/Makefile b/Makefile
index e1a5c187..906dc5bb 100644
--- a/Makefile
+++ b/Makefile
@@ -19,6 +19,12 @@ $(AUTOLOADS): php-project.el php-mode.el
 clean:
 	rm -f $(ELCS) $(AUTOLOADS)
 
+# Perform any operations that will be useful for developers
+# who contribute to PHP Mode.
+dev:
+	cp etc/git/prepare-commit-msg .git/hooks/prepare-commit-msg
+	chmod u+x .git/hooks/prepare-commit-msg
+	
 # Runs all unit tests from php-mode-test.el and shows the results. The
 # script will exit with the status code zero if all tests pass. If any
 # test fails the script exits with a non-zero status and shows
diff --git a/etc/git/commit-template.txt b/etc/git/commit-template.txt
new file mode 100644
index 00000000..376efaf6
--- /dev/null
+++ b/etc/git/commit-template.txt
@@ -0,0 +1,13 @@
+# SUBJECT, 50 Characters, No Period
+# "If applied, this commit will..."
+
+# BODY, 72 Characters
+# Answers the question, "Why?", not, "How?"
+
+# METADATA
+# GitHub-Issue:
+# Resolves:
+# See-also:
+# Reviewed-by:
+# Special-thanks:
+# HANGING INDENT
diff --git a/etc/git/prepare-commit-msg b/etc/git/prepare-commit-msg
new file mode 100755
index 00000000..6e3a8006
--- /dev/null
+++ b/etc/git/prepare-commit-msg
@@ -0,0 +1,35 @@
+#!/bin/sh
+#
+# prepare-commit-msg
+# ==================
+#
+# ## SYNOPSIS
+#
+# This hook fills the user's editor with a pre-written commit message
+# template, intended to help contributors adhere to good style and
+# practices when it comes to writing Git commit messages.
+#
+########################################################################
+
+# This hook will always recieve three arguments.  We only care about the
+# first for our purposes, but still assign useful names to the others
+# in case we need them in the future.
+COMMIT_MESSAGE=$1
+COMMIT_SOURCE=$2
+COMMIT_SHA1=$3
+
+# If the commit message already contains content then the developer
+# is probably using his or her own template.  In which case we do not
+# trample over it.  We test for a pre-existing template by reading
+# the first line of the commit message this hook recieved, and check
+# so see if it is an empty string (apply our template) or not (leave
+# the message alone).
+TITLE_LINE=$(head -n1 $COMMIT_MESSAGE)
+
+if [ -z "$TITLE_LINE" ]; then
+	project_dir=$(git rev-parse --show-toplevel)
+	template="$project_dir/etc/git/commit-template.txt"
+	echo "$(cat $template)\n$(cat $COMMIT_MESSAGE)" > $COMMIT_MESSAGE
+fi
+
+exit 0