From 917c4b988cccdc48cfa4c81bcf235572c825d7be Mon Sep 17 00:00:00 2001
From: Steve LLamb <38917682+SteveLLamb@users.noreply.github.com>
Date: Fri, 22 Aug 2025 12:03:13 -0700
Subject: [PATCH 1/5] Enforce offical Tooling

---
 workflows/action.yml | 66 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/workflows/action.yml b/workflows/action.yml
index 175a993..2472d48 100644
--- a/workflows/action.yml
+++ b/workflows/action.yml
@@ -11,6 +11,15 @@ inputs:
     required: true
   GITHUB_TOKEN:
     required: true
+  OFFICIAL_SUBMODULE_PATH:
+    required: false
+    default: tooling
+  OFFICIAL_SUBMODULE_URL:
+    required: false
+    default: https://github.com/SMPTE/html-pub.git
+  OFFICIAL_SUBMODULE_BRANCH:
+    required: false
+    default: main
 
 runs:
   using: "composite"
@@ -20,6 +29,63 @@ runs:
       shell: bash
       run: cmp ${GITHUB_ACTION_PATH}/../.github/workflows/main.yml .github/workflows/main.yml
 
+    - name: Enforce official submodule lock
+      shell: bash
+      env:
+        SUB_PATH: ${{ inputs.OFFICIAL_SUBMODULE_PATH }}
+        OFFICIAL_URL: ${{ inputs.OFFICIAL_SUBMODULE_URL }}
+        OFFICIAL_BRANCH: ${{ inputs.OFFICIAL_SUBMODULE_BRANCH }}
+      run: |
+        set -euo pipefail
+
+        if [[ -z "${SUB_PATH:-}" ]]; then
+          echo "ERROR: SUB_PATH is empty"; exit 1
+        fi
+
+        if [[ ! -f ".gitmodules" ]]; then
+          echo "ERROR: .gitmodules not found. This repository must declare the '${SUB_PATH}' submodule."
+          exit 1
+        fi
+
+        URL_IN_MODULES=$(git config -f .gitmodules --get "submodule.${SUB_PATH}.url" || true)
+        if [[ "$URL_IN_MODULES" != "$OFFICIAL_URL" ]]; then
+          echo "ERROR: ${SUB_PATH} URL in .gitmodules is '$URL_IN_MODULES' but must be '$OFFICIAL_URL'"
+          exit 1
+        fi
+
+        RECORDED_SHA=$(git ls-tree HEAD "$SUB_PATH" | awk '{print $3}')
+        if [[ -z "${RECORDED_SHA:-}" ]]; then
+          echo "ERROR: No submodule commit recorded for ${SUB_PATH}. Did you add and commit the submodule?"
+          exit 1
+        fi
+
+        OFFICIAL_SHA=$(git ls-remote "$OFFICIAL_URL" "refs/heads/$OFFICIAL_BRANCH" | awk '{print $1}')
+        if [[ -z "${OFFICIAL_SHA:-}" ]]; then
+          echo "ERROR: Could not read '$OFFICIAL_BRANCH' from '$OFFICIAL_URL'"
+          exit 1
+        fi
+
+        echo "Recorded(${SUB_PATH}): $RECORDED_SHA"
+        echo "Official ($OFFICIAL_BRANCH): $OFFICIAL_SHA"
+
+        if [[ "$RECORDED_SHA" != "$OFFICIAL_SHA" ]]; then
+          cat <<'MSG'
+ERROR: Submodule is not on latest official main.
+
+To fix locally:
+  git submodule update --init --remote -- "${SUB_PATH}"
+  # or explicitly:
+  cd "${SUB_PATH}"
+  git fetch origin "${OFFICIAL_BRANCH}"
+  git checkout --detach "origin/${OFFICIAL_BRANCH}"
+  cd -
+  git add "${SUB_PATH}"
+  git commit -m "Bump ${SUB_PATH} to latest ${OFFICIAL_BRANCH}"
+
+MSG
+          exit 1
+        fi
+
     - name: Install vnu
       shell: bash
       run: sudo pip install html5validator==0.4.2

From f9a5836b0780d4bcfad7e9db029f11820724d7c5 Mon Sep 17 00:00:00 2001
From: Steve LLamb <38917682+SteveLLamb@users.noreply.github.com>
Date: Fri, 22 Aug 2025 12:09:29 -0700
Subject: [PATCH 2/5] change to echo

---
 workflows/action.yml | 25 +++++++++++--------------
 1 file changed, 11 insertions(+), 14 deletions(-)

diff --git a/workflows/action.yml b/workflows/action.yml
index 2472d48..1935c7f 100644
--- a/workflows/action.yml
+++ b/workflows/action.yml
@@ -69,20 +69,17 @@ runs:
         echo "Official ($OFFICIAL_BRANCH): $OFFICIAL_SHA"
 
         if [[ "$RECORDED_SHA" != "$OFFICIAL_SHA" ]]; then
-          cat <<'MSG'
-ERROR: Submodule is not on latest official main.
-
-To fix locally:
-  git submodule update --init --remote -- "${SUB_PATH}"
-  # or explicitly:
-  cd "${SUB_PATH}"
-  git fetch origin "${OFFICIAL_BRANCH}"
-  git checkout --detach "origin/${OFFICIAL_BRANCH}"
-  cd -
-  git add "${SUB_PATH}"
-  git commit -m "Bump ${SUB_PATH} to latest ${OFFICIAL_BRANCH}"
-
-MSG
+          echo "ERROR: Submodule is not on latest official main."
+          echo
+          echo "To fix locally:"
+          echo "  git submodule update --init --remote -- \"${SUB_PATH}\""
+          echo "  # or explicitly:"
+          echo "  cd \"${SUB_PATH}\""
+          echo "  git fetch origin \"${OFFICIAL_BRANCH}\""
+          echo "  git checkout --detach \"origin/${OFFICIAL_BRANCH}\""
+          echo "  cd -"
+          echo "  git add \"${SUB_PATH}\""
+          echo "  git commit -m \"Bump ${SUB_PATH} to latest ${OFFICIAL_BRANCH}\""
           exit 1
         fi
 

From 88851031603caff74e791fd8dfedd743db29f172 Mon Sep 17 00:00:00 2001
From: Steve LLamb <38917682+SteveLLamb@users.noreply.github.com>
Date: Fri, 22 Aug 2025 12:12:05 -0700
Subject: [PATCH 3/5] skip self check

---
 workflows/action.yml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/workflows/action.yml b/workflows/action.yml
index 1935c7f..442f91c 100644
--- a/workflows/action.yml
+++ b/workflows/action.yml
@@ -38,6 +38,12 @@ runs:
       run: |
         set -euo pipefail
 
+        # Skip enforcement when running inside the source repository itself.
+        if [[ "${GITHUB_REPOSITORY:-}" == "SMPTE/html-pub" ]]; then
+          echo "Submodule enforcement skipped in source repo (${GITHUB_REPOSITORY})."
+          exit 0
+        fi
+
         if [[ -z "${SUB_PATH:-}" ]]; then
           echo "ERROR: SUB_PATH is empty"; exit 1
         fi

From 4dcb654a29caa5ad607d906bdf6a9e943de99222 Mon Sep 17 00:00:00 2001
From: Steve LLamb <38917682+SteveLLamb@users.noreply.github.com>
Date: Fri, 22 Aug 2025 12:38:52 -0700
Subject: [PATCH 4/5] add in override

---
 .github/workflows/main.yml |  1 +
 workflows/action.yml       | 59 ++++++++++++++++++++++++++------------
 2 files changed, 41 insertions(+), 19 deletions(-)

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 71f7a29..b3a9c2c 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -56,6 +56,7 @@ jobs:
           AWS_S3_KEY_PREFIX: "${{env.REPOSITORY_NAME}}/"
           CANONICAL_LINK_PREFIX: ${{env.CANONICAL_LINK_PREFIX}}
           GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+          OVERRIDE_SUBMODULE_SHA: ""
 
       - name: Build and deploy document (HTML Pub repo)
         uses: ./workflows
diff --git a/workflows/action.yml b/workflows/action.yml
index 442f91c..5466b5e 100644
--- a/workflows/action.yml
+++ b/workflows/action.yml
@@ -20,6 +20,10 @@ inputs:
   OFFICIAL_SUBMODULE_BRANCH:
     required: false
     default: main
+  OVERRIDE_SUBMODULE_SHA:
+    required: false
+  OVERRIDE_SUBMODULE_REF:
+    required: false
 
 runs:
   using: "composite"
@@ -35,6 +39,8 @@ runs:
         SUB_PATH: ${{ inputs.OFFICIAL_SUBMODULE_PATH }}
         OFFICIAL_URL: ${{ inputs.OFFICIAL_SUBMODULE_URL }}
         OFFICIAL_BRANCH: ${{ inputs.OFFICIAL_SUBMODULE_BRANCH }}
+        OVERRIDE_SHA: ${{ inputs.OVERRIDE_SUBMODULE_SHA }}
+        OVERRIDE_REF: ${{ inputs.OVERRIDE_SUBMODULE_REF }}
       run: |
         set -euo pipefail
 
@@ -65,28 +71,43 @@ runs:
           exit 1
         fi
 
-        OFFICIAL_SHA=$(git ls-remote "$OFFICIAL_URL" "refs/heads/$OFFICIAL_BRANCH" | awk '{print $1}')
-        if [[ -z "${OFFICIAL_SHA:-}" ]]; then
-          echo "ERROR: Could not read '$OFFICIAL_BRANCH' from '$OFFICIAL_URL'"
-          exit 1
+        if [[ -n "${OVERRIDE_SHA:-}" ]]; then
+          TARGET_SHA="$OVERRIDE_SHA"
+        elif [[ -n "${OVERRIDE_REF:-}" ]]; then
+          TARGET_SHA=$(git ls-remote "$OFFICIAL_URL" "$OVERRIDE_REF" | awk '{print $1}')
+          if [[ -z "${TARGET_SHA:-}" ]]; then
+            echo "ERROR: Could not read override ref '$OVERRIDE_REF' from '$OFFICIAL_URL'"
+            exit 1
+          fi
+        else
+          TARGET_SHA=$(git ls-remote "$OFFICIAL_URL" "refs/heads/$OFFICIAL_BRANCH" | awk '{print $1}')
+          if [[ -z "${TARGET_SHA:-}" ]]; then
+            echo "ERROR: Could not read '$OFFICIAL_BRANCH' from '$OFFICIAL_URL'"
+            exit 1
+          fi
         fi
 
         echo "Recorded(${SUB_PATH}): $RECORDED_SHA"
-        echo "Official ($OFFICIAL_BRANCH): $OFFICIAL_SHA"
-
-        if [[ "$RECORDED_SHA" != "$OFFICIAL_SHA" ]]; then
-          echo "ERROR: Submodule is not on latest official main."
-          echo
-          echo "To fix locally:"
-          echo "  git submodule update --init --remote -- \"${SUB_PATH}\""
-          echo "  # or explicitly:"
-          echo "  cd \"${SUB_PATH}\""
-          echo "  git fetch origin \"${OFFICIAL_BRANCH}\""
-          echo "  git checkout --detach \"origin/${OFFICIAL_BRANCH}\""
-          echo "  cd -"
-          echo "  git add \"${SUB_PATH}\""
-          echo "  git commit -m \"Bump ${SUB_PATH} to latest ${OFFICIAL_BRANCH}\""
-          exit 1
+        echo "Target  (${SUB_PATH}): $TARGET_SHA"
+
+        if [[ "$RECORDED_SHA" != "$TARGET_SHA" ]]; then
+          if [[ -n "${OVERRIDE_SHA:-}" || -n "${OVERRIDE_REF:-}" ]]; then
+            echo "::warning::Submodule commit mismatch (override active). Recorded=${RECORDED_SHA} Target=${TARGET_SHA}"
+            # Do not exit; proceed to allow testing with override.
+          else
+            echo "ERROR: Submodule is not on latest official main."
+            echo
+            echo "To fix locally:"
+            echo "  git submodule update --init --remote -- \"${SUB_PATH}\""
+            echo "  # or explicitly:"
+            echo "  cd \"${SUB_PATH}\""
+            echo "  git fetch origin \"${OFFICIAL_BRANCH}\""
+            echo "  git checkout --detach \"origin/${OFFICIAL_BRANCH}\""
+            echo "  cd -"
+            echo "  git add \"${SUB_PATH}\""
+            echo "  git commit -m \"Bump ${SUB_PATH} to latest ${OFFICIAL_BRANCH}\""
+            exit 1
+          fi
         fi
 
     - name: Install vnu

From aa6d819ac471c8e2628b9aadc4715faae4ee3ebd Mon Sep 17 00:00:00 2001
From: Steve LLamb <38917682+SteveLLamb@users.noreply.github.com>
Date: Fri, 22 Aug 2025 12:50:35 -0700
Subject: [PATCH 5/5] ignore overrider line on comp

---
 workflows/action.yml | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/workflows/action.yml b/workflows/action.yml
index 5466b5e..56c8763 100644
--- a/workflows/action.yml
+++ b/workflows/action.yml
@@ -31,7 +31,14 @@ runs:
 
     - name: Confirm that the right workflow is active
       shell: bash
-      run: cmp ${GITHUB_ACTION_PATH}/../.github/workflows/main.yml .github/workflows/main.yml
+      run: |
+        set -euo pipefail
+        REF="${GITHUB_ACTION_PATH}/../.github/workflows/main.yml"
+        LOC=".github/workflows/main.yml"
+        # Ignore override inputs so they don't trigger false diffs
+        diff -u \
+          <(grep -vE '^[[:space:]]*OVERRIDE_SUBMODULE_(SHA|REF):' "$REF") \
+          <(grep -vE '^[[:space:]]*OVERRIDE_SUBMODULE_(SHA|REF):' "$LOC")
 
     - name: Enforce official submodule lock
       shell: bash