Add comments to submodule check

Author: newhoggy

.github/workflows/submodule-check.yml

@@ -18,7 +18,14 @@ jobs:
       with:
         submodules: true
 
-    - name: Check submodules
+    - # Only PRs where all the submodules are on the main branch of their respective repositories
+      # are allowed to merge to main.
+      #
+      # The script can be run locally to confirm that the submodules are on the main branch.
+      #
+      # Note, the main branch of submodule repositories have a name other than "main".
+      # For example: "master" or "develop".
+      name: Check submodules
       env:
         GH_TOKEN: ${{ github.token }}
       run: ./scripts/ci/require-submodules-on-main-branch.sh

scripts/ci/require-submodules-on-main-branch.sh

@@ -1,6 +1,12 @@
 #!/usr/bin/env bash
+#
+# This script checks that all submodules are on the main branch when the main branch of the repository is main.
+#
+# The script exits with a non-zero exit code if any submodules are not on the main branch.
 
+# TODO: Use this initialisation of main_branch once the repository is made public
 # main_branch=$(gh repo view --json defaultBranchRef | jq -r .defaultBranchRef.name)
+
 main_branch=main
 mismatches=0
 toplevel="$(git rev-parse --show-toplevel)"