From a52abd866f79880ae0703b2026ca9908ebc5f663 Mon Sep 17 00:00:00 2001
From: Matthias Kay <matthias.kay@hlag.com>
Date: Mon, 6 Jan 2025 13:24:20 +0100
Subject: [PATCH] docs

---
 .github/workflows/default_spelling_callable.yml |  2 +-
 .github/workflows/scripts/check_dictionaries.sh |  9 +++++++--
 README.md                                       | 11 +++++++++--
 3 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/default_spelling_callable.yml b/.github/workflows/default_spelling_callable.yml
index 5f5bf15..fe2148a 100644
--- a/.github/workflows/default_spelling_callable.yml
+++ b/.github/workflows/default_spelling_callable.yml
@@ -28,7 +28,7 @@ jobs:
         with:
           list-files: "shell"
           filters: |
-            markdown:
+            dictionaries:
             - added|modified: '.config/dictionaries/*.txt'
     outputs:
       dictionaries: ${{ steps.changes-for-shell.outputs.dictionaries }}
diff --git a/.github/workflows/scripts/check_dictionaries.sh b/.github/workflows/scripts/check_dictionaries.sh
index 27f63c7..15dff8c 100755
--- a/.github/workflows/scripts/check_dictionaries.sh
+++ b/.github/workflows/scripts/check_dictionaries.sh
@@ -1,5 +1,10 @@
 #!/bin/bash
 
+#
+# Based on the idea outlined in https://github.com/streetsidesoftware/cspell/issues/2536#issuecomment-1126077282
+# but with a few modifications to fit the needs of our project.
+#
+
 set -euo pipefail
 
 MISSPELLED_WORDS_PATH="misspelled-words.txt"
@@ -15,14 +20,14 @@ npx cspell . --dot --no-progress --no-summary --unique --words-only --no-exit-co
 # Check the custom dictionaries
 ONE_OR_MORE_FAILURES=0
 for DICTIONARY_NAME in "${DICTIONARY_FILES_TO_CHECK[@]}"; do
-  # Check alphabetically sorted and unique
   echo "Checking for orphaned words in dictionary: $DICTIONARY_NAME"
 
   # ensure the dictionary is sorted and unique
-  sort --ignore-case --unique --check "$DICTIONARY_NAME"
+  sort --ignore-case --unique --check "$DICTIONARY_NAME" > /dev/null
 
   # Check that each word in the dictionary is actually being used
   while IFS= read -r line; do
+    # Remove any trailing newline characters
     line=$(echo "$line" | tr -d '\r\n')
 
     if ! grep "$line" "$MISSPELLED_WORDS_PATH" --ignore-case --silent ; then
diff --git a/README.md b/README.md
index e4dffbc..3b4939e 100644
--- a/README.md
+++ b/README.md
@@ -27,14 +27,15 @@ all files in case of major changes in the templates.
 - linters for all files
 - PRs are checked for semantic commit titles to ensure an automatic release
 - ChatOps to run workflows from comments
+- a `.config/dictionaries/project.txt` file for the spell checker exceptions
 
 ## For Developers - Repository Layout
 
 1. Add all workflows to `.github/workflows/`, otherwise they can't be referenced from the repositories.
 2. Workflows with `this_` prefix are used for this repository only.
-3. Workflows with `default_` prefix are added to every new repository. Otherwise use the correct prefix for the project type.
+3. Workflows with `default_` prefix are added to every new repository. Otherwise, use the correct prefix for the project type.
 
-The script to set up the workflows for new repositories is `setup-workflows.sh`. It copies the necessary files to the new
+The script to set up the workflows for new repositories is `update-workflows.sh`. It copies the necessary files to the new
 repository. It starts with the default workflows and adds the specific ones based on the project type. In case of a filename clash,
 the specific template overwrites the default one (exception: `.gitignore` These files are concatenated).
 
@@ -50,3 +51,9 @@ Use
 
 in the file to describe the triggers which should be used in the repository. The script will automatically replace the triggers
 marked with `USE_WORKFLOW` which are valid within this repository only.
+
+### Spell Checker
+
+1. Add the words to the `.config/dictionaries/workflow.txt` file.
+2. `.config/dictionaries/project.txt` file is used for the project specific words of the project being set up.
+3. All other dictionaries are managed by the `Repository-Template-*` repositories.