chore(common/resources): add documentation for scopes

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"
 }
 

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

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/

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
+    }
+  }
+}

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
+    }
+  }
+}