add comments explaining the perl script

.github/workflows/copy-workflow.yml

@@ -111,14 +111,20 @@ jobs:
         config=$(echo -e "$config" | jq -c '.')
         github="{\"default_branch\":\"${{ env.DEFAULT_BRANCH }}\"}"
         context="{\"config\":$config,\"github\":$github}"
+        # matches trimmed string between template context delimiters
         regexp='\$\{\{\{\s*(.*?)\s*\}\}\}'
+        # replacement is a perl script that:
+        # 1. prepends . to the matched string to create a filter
+        # 2. escapes single quotes by replacing ' with '"'"' in filter
+        # 3. prints context escaped in the same manner
+        # 4. applies jq with filter to the stdout
         replacement="\$filter = \".\$1\"; \$filter =~ s/'/'\"'\"'/g; \`echo '${context//\'/\'\"\'\"\'}' | jq -jc '\$filter'\`"
         for f in $(jq -r '.[]' <<< ${{ toJson(env.FILES) }}); do
           echo -e "\nProcessing $f."
           # add DO NOT EDIT header
           tmp=$(mktemp)
           cat $TEMPLATE_REPO_DIR/$TEMPLATE_DIR/header.yml $TEMPLATE_REPO_DIR/$TEMPLATE_DIR/$f > $tmp
-          # replace template expressions with values from the JSON context object
+          # replace template contexts with values from the JSON context object
           perl -pi -e "s#$regexp#$replacement#ge" $tmp
           mv $tmp $TEMPLATE_REPO_DIR/$TEMPLATE_DIR/$f
           # create commit, if necessary

templates/README.md

@@ -2,6 +2,10 @@
 
 This directory contains template files that can be expanded and copied over to the configured repositories.
 
+## Header
+
+The [header](header.yml) is prepended to all the files before they are copied to the target repositories.
+
 ## Contexts
 
 You can access context information during template expansion(before copy is performed).
@@ -38,7 +42,7 @@ The `config` context is the configuration object because of which the file is be
 The `github` context contains information about the target repository the file is being copied to.
 
 | Property name | Type | Always present | Description |
-| --- | --- | --- |
+| --- | --- | --- | --- |
 | `github` | `object` | `true` | The top-level context. |
 | `github.default_branch` | `string` | `true` | The name of the default branch of the target repository. |
 
@@ -53,7 +57,7 @@ The `github` context contains information about the target repository the file i
             "greeting": "Hello"
         },
         "files": [],
-        "extra_files": [".github/workflows/example.yml"]
+        "extra_files": [".github/workflows/example.yml"],
         "target": "protocol/.github-test-target"
     },
     "github": {