added comments

Author: DrisDary

.github/scripts/build-matrix.sh

@@ -4,22 +4,26 @@ set -euo pipefail
 # Builds a dynamic GitHub Actions matrix for run-samples.yml.
 # Usage: build-matrix.sh <run_mode> [base_sha]
 
+# "all" runs every test; "changed" only runs tests whose watch_folders have modified files
 RUN_MODE="${1:-all}"
 BASE_SHA="${2:-}"
 
+# Get JSON metadata for all tests from run-samples.sh --list
 chmod +x ./run-samples.sh
 TEST_META=$(./run-samples.sh --list)
 TOTAL=$(echo "$TEST_META" | jq length)
 echo "Run mode: $RUN_MODE | Total tests: $TOTAL"
 
+# Changes to these files affect all tests, so any modification triggers a full run
 INFRA_FILES="run-samples.sh Makefile .github/workflows/run-samples.yml .github/scripts/build-matrix.sh pyproject.toml requirements-dev.txt requirements-runtime.txt"
 
 if [[ "$RUN_MODE" == "changed" && -n "$BASE_SHA" ]]; then
+  # Get list of files changed between base branch and current HEAD
   CHANGED=$(git diff --name-only "$BASE_SHA"..HEAD || true)
   echo "Changed files:"
   echo "$CHANGED"
 
-  # If any infrastructure file changed, run all tests
+  # Safety net: if any infrastructure file changed, run all tests
   RUN_ALL=false
   for f in $INFRA_FILES; do
     if echo "$CHANGED" | grep -qF "$f"; then
@@ -31,6 +35,7 @@ if [[ "$RUN_MODE" == "changed" && -n "$BASE_SHA" ]]; then
   if [[ "$RUN_ALL" == "true" ]]; then
     INDICES=$(seq 0 $((TOTAL-1)))
   else
+    # Match changed files against each test's watch_folders using prefix matching
     INDICES=""
     for (( i=0; i<TOTAL; i++ )); do
       mapfile -t folders < <(echo "$TEST_META" | jq -r ".[$i].watch_folders[]")
@@ -43,15 +48,18 @@ if [[ "$RUN_MODE" == "changed" && -n "$BASE_SHA" ]]; then
     INDICES=$(echo "$INDICES" | xargs)
   fi
 else
+  # "all" mode: select every test
   INDICES=$(seq 0 $((TOTAL-1)))
 fi
 
+# Output the matrix JSON for GitHub Actions
 if [[ -z "${INDICES:-}" ]]; then
   echo "No tests to run."
   echo "has_tests=false" >> "$GITHUB_OUTPUT"
   echo 'matrix={"include":[]}' >> "$GITHUB_OUTPUT"
 else
   echo "has_tests=true" >> "$GITHUB_OUTPUT"
+  # Convert space-separated indices to JSON array, then build the matrix object
   IDX_JSON=$(echo "$INDICES" | tr ' ' '\n' | jq -R 'tonumber' | jq -s '.')
   MATRIX=$(echo "$TEST_META" | jq -c --argjson idx "$IDX_JSON" \
     '{include: [$idx[] as $i | .[$i] | {shard, splits, name}]}')

.github/workflows/run-samples.yml

@@ -26,6 +26,7 @@ env:
   DEFAULT_RUN_MODE: changed
 
 jobs:
+  # Lightweight job that builds the dynamic test matrix for the main test jobs
   setup:
     name: "Build Test Matrix"
     runs-on: ubuntu-latest
@@ -36,18 +37,19 @@ jobs:
       - name: Checkout repo
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0
+          fetch-depth: 0  # Full history needed for git diff in "changed" mode
 
       - name: Build dynamic matrix
         id: build-matrix
         run: |
-          # Determine run mode and base SHA, then delegate to the build-matrix script
+          # Pick run mode: manual dispatch uses the dropdown, PRs use the env default
           if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
             RUN_MODE="${{ github.event.inputs.run_mode }}"
           else
             RUN_MODE="${{ env.DEFAULT_RUN_MODE }}"
           fi
 
+          # In "changed" mode, determine the base commit to diff against
           BASE_SHA=""
           if [[ "$RUN_MODE" == "changed" ]]; then
             if [[ "${{ github.event_name }}" == "pull_request" ]]; then
@@ -60,10 +62,11 @@ jobs:
           chmod +x .github/scripts/build-matrix.sh
           .github/scripts/build-matrix.sh "$RUN_MODE" "$BASE_SHA"
 
+  # Each test runs in its own job — one matrix entry per test from the setup job
   scripts:
     name: "Test: ${{ matrix.name }}"
     needs: setup
-    if: needs.setup.outputs.has_tests == 'true'
+    if: needs.setup.outputs.has_tests == 'true'  # Skip entirely when no tests match
     environment: AZURE
     strategy:
       fail-fast: false

run-samples.sh

@@ -60,6 +60,8 @@ ALL_SAMPLES=("${SAMPLES[@]}" "${TERRAFORM_SAMPLES[@]}" "${BICEP_SAMPLES[@]}")
 TOTAL=${#ALL_SAMPLES[@]}
 
 # 2. Handle --list flag: output JSON metadata for CI matrix generation (no tools required)
+#    Each entry has: shard (1-based index), splits (total count), name, and watch_folders.
+#    CI uses watch_folders to detect which tests are affected by changed files.
 if [[ "${1:-}" == "--list" ]]; then
   echo "["
   for (( i=0; i<TOTAL; i++ )); do
@@ -126,21 +128,23 @@ else
   az account show --query "{Environment:environmentName, Subscription:id}" --output json 2>&1 || echo "[DEBUG] az account show failed"
 fi
 
-# 6. Calculate Shard
+# 6. Calculate Shard — determines which slice of ALL_SAMPLES to run.
+#    When SPLITS=TOTAL, each shard runs exactly 1 test (COUNT=1).
 SHARD=${1:-1}
 SPLITS=${2:-1}
 
 COUNT=$(( TOTAL / SPLITS ))
 START=$(( (SHARD - 1) * COUNT ))
 
+# Last shard picks up any remainder from integer division
 if [ "$SHARD" -eq "$SPLITS" ]; then
   COUNT=$(( TOTAL - START ))
 fi
 
 echo "Running samples shard $SHARD of $SPLITS (index $START, count $COUNT)"
 echo "Total samples (scripts + terraform + bicep): $TOTAL"
 
-# 7. Run Samples
+# 7. Run Samples — deploy each test, then run its validation if defined
 for (( i=START; i<START+COUNT; i++ )); do
   item="${ALL_SAMPLES[$i]}"
   IFS='|' read -r path deploy test <<< "$item"