From c60df18ee07bad448121b8ff20f0a4b249a4ede7 Mon Sep 17 00:00:00 2001
From: Marc Durdin <marc@durdin.net>
Date: Tue, 19 May 2020 17:31:17 +1000
Subject: [PATCH] chore(common/resources): add documentation for scopes

---
 resources/git-hooks/commit-msg            |  6 ++++++
 resources/git-hooks/commit-msg-defs       |  2 +-
 resources/scopes/README.md                | 20 ++++++++++++++++++++
 resources/scopes/commit-types.schema.json | 19 +++++++++++++++++++
 resources/scopes/scopes.schema.json       | 19 +++++++++++++++++++
 5 files changed, 65 insertions(+), 1 deletion(-)
 create mode 100644 resources/scopes/README.md
 create mode 100644 resources/scopes/commit-types.schema.json
 create mode 100644 resources/scopes/scopes.schema.json

diff --git a/resources/git-hooks/commit-msg b/resources/git-hooks/commit-msg
index b027025dfe..b7359229fa 100755
--- a/resources/git-hooks/commit-msg
+++ b/resources/git-hooks/commit-msg
@@ -18,6 +18,10 @@ HOOK_DIRECTORY="$(dirname "$(greadlink -f "${BASH_SOURCE[0]}" 2>/dev/null || rea
 . "$HOOK_DIRECTORY/../build/jq.inc.sh"
 . "$HOOK_DIRECTORY/commit-msg-defs"
 
+#
+# Read from our globally shared JSON-formatted scopes and types
+#
+
 scopes=( $("$JQ" -r '[.scopes | paths | reduce .[] as $item (""; if . == "" then $item else . + "/" + $item end)] | join(" ")' < "$HOOK_DIRECTORY/../scopes/scopes.json") )
 types=( $("$JQ" -r '.commitTypes | join(" ")' < "$HOOK_DIRECTORY/../scopes/commit-types.json") )
 
@@ -96,6 +100,8 @@ function print_error() {
   echo -e "${t_cyn}Example:${t_end} fix(windows): Re-attaches the widget plug which had fallen out. Fixes #1111"
   echo -e "${t_cyn}Reference${t_end}: https://github.com/keymanapp/keyman/wiki/Pull-Request-and-Commit-workflow-notes"
   echo -e ""
+  echo -e "Tips: Don't include a period at the end of the first line; best to put 'Fixes #1111' on a line of its own."
+  echo -e ""
   echo -e "This script: $0"
 }
 
diff --git a/resources/git-hooks/commit-msg-defs b/resources/git-hooks/commit-msg-defs
index c1ad9477d1..f48794c11e 100755
--- a/resources/git-hooks/commit-msg-defs
+++ b/resources/git-hooks/commit-msg-defs
@@ -1,5 +1,5 @@
 #!/bin/bash
-# Configurable options for types, scopes and message length.
+# Configurable options for message length.
 #
 
 min_length=4
diff --git a/resources/scopes/README.md b/resources/scopes/README.md
new file mode 100644
index 0000000000..372a2f60e5
--- /dev/null
+++ b/resources/scopes/README.md
@@ -0,0 +1,20 @@
+# Scopes and Commit Types
+
+This folder contains definitions for valid scopes and commit types for Keyman.
+
+## scopes.json
+
+* A tree structured JSON object, with root node `"scopes"`.
+* Keys must have lower case alpha names; leaf nodes must always be `null`.
+
+## commit-types.json
+
+* A JSON object with a single property: `"commitTypes"` which must be an array of strings.
+* Values in the array must contain lower case alphabetical letters only.
+
+# Schemas
+
+* scopes.schema.json
+* commit-types.schema.json
+
+Any changes MUST be validated against these schemas before commit. One online tool that does this: https://www.jsonschemavalidator.net/
diff --git a/resources/scopes/commit-types.schema.json b/resources/scopes/commit-types.schema.json
new file mode 100644
index 0000000000..709b8ccf51
--- /dev/null
+++ b/resources/scopes/commit-types.schema.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/schema#",
+  "$ref": "#/definitions/commitTypes",
+  "definitions": {
+    "commitTypes": {
+      "type": "object",
+      "properties": {
+        "commitTypes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z]+$"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}
\ No newline at end of file
diff --git a/resources/scopes/scopes.schema.json b/resources/scopes/scopes.schema.json
new file mode 100644
index 0000000000..4fd1eb8c6c
--- /dev/null
+++ b/resources/scopes/scopes.schema.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/schema#",
+  "$ref": "#/definitions/scopes",
+
+  "definitions": {
+    "scopes": {
+      "type": "object",
+      "patternProperties": {
+        "^[a-z]+$": {
+          "anyOf": [
+            {"$ref": "#/definitions/scopes"},
+            {"type": "null"}
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}
\ No newline at end of file