ci: make documentation sync smarter by filtering changes

Optimizes the sync workflow to prevent creating empty Pull Requests by
inspecting submodule diff history for documentation shifts (e.g., edits
inside docs/ or modifications addressing README.md).

Extends the automation to generate dynamic Pull Request descriptions
listing the exact relevant files that triggered the synchronizer.

Assisted-by: gemini-3.1-pro-high
Signed-off-by: Samuel Karp <samuelkarp@google.com>

Author: samuelkarp

.github/workflows/sync-documentation.yml

@@ -11,18 +11,37 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Record submodule state
+        run: ./tools/check-submodule-docs.sh record > /tmp/old_submodules.txt
       - name: Update documentation
         run: make refresh-docs
+      - name: Check for documentation changes
+        id: verify_changes
+        run: |
+          if ./tools/check-submodule-docs.sh check /tmp/old_submodules.txt /tmp/pr_body.txt; then
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            {
+              echo 'pr_body<<EOF'
+              echo "This is an auto-generated PR to sync updates in the main containerd project's documentation."
+              echo ''
+              echo '### Relevant changes detected:'
+              cat /tmp/pr_body.txt
+              echo 'EOF'
+            } >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+          fi
       - name: Create Pull Request
+        if: steps.verify_changes.outputs.has_changes == 'true'
         uses: peter-evans/create-pull-request@v7
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           commit-message: |
-            keep releases.md in sync with containerd/containerd
+            keep documentation in sync with containerd/containerd
 
             Signed-off-by: Samuel Karp <samuelkarp+automated@google.com>
           committer: Samuel Karp <samuelkarp@google.com>
           author: Samuel Karp <samuelkarp+automated@google.com>
           title: Automated documentation sync update
-          body: This is an auto-generated PR to sync updates in the main containerd project's documentation.
+          body: ${{ steps.verify_changes.outputs.pr_body }}
           branch: docs-updates

tools/check-submodule-docs.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+set -e
+
+COMMAND=$1
+
+case "$COMMAND" in
+    record)
+        while read -r line; do
+            hash=$(echo "$line" | grep -oE '[0-9a-f]{40}')
+            path=$(echo "$line" | awk '{print $2}')
+            if [ -n "$hash" ] && [ -n "$path" ]; then
+                echo "$path $hash"
+            fi
+        done < <(git submodule status)
+        ;;
+    check)
+        STATE_FILE=$2
+        REPORT_FILE=$3
+        if [ ! -f "$STATE_FILE" ]; then
+            echo "Error: State file $STATE_FILE not found" >&2
+            exit 2
+        fi
+
+        [ -n "$REPORT_FILE" ] && rm -f "$REPORT_FILE"
+
+        declare -A old_hashes
+        while read -r line; do
+            path=$(echo "$line" | awk '{print $1}')
+            hash=$(echo "$line" | awk '{print $2}')
+            old_hashes["$path"]="$hash"
+        done < "$STATE_FILE"
+
+        has_relevant_changes=false
+
+        while read -r line; do
+            new_hash=$(echo "$line" | grep -oE '[0-9a-f]{40}')
+            path=$(echo "$line" | awk '{print $2}')
+            old_hash=${old_hashes["$path"]}
+
+            if [ -n "$old_hash" ] && [ "$new_hash" != "$old_hash" ]; then
+                echo "Submodule $path updated: $old_hash -> $new_hash"
+                diff_output=$(git -C "$path" diff "$old_hash" "$new_hash" --name-only 2>/dev/null | grep -E "^(docs/|README\.md)" || true)
+                if [ -n "$diff_output" ]; then
+                    echo "--> Relevant changes found in $path"
+                    has_relevant_changes=true
+                    if [ -n "$REPORT_FILE" ]; then
+                        echo "#### $path" >> "$REPORT_FILE"
+                        echo "$diff_output" | sed 's/^/- /' >> "$REPORT_FILE"
+                        echo "" >> "$REPORT_FILE"
+                    fi
+                fi
+            fi
+        done < <(git submodule status)
+
+        if [ "$has_relevant_changes" = true ]; then
+            echo "Result: Relevant changes detected."
+            exit 0
+        else
+            echo "Result: No relevant changes."
+            exit 1
+        fi
+        ;;
+    *)
+        echo "Usage: $0 {record|check [state_file]}" >&2
+        exit 3
+        ;;
+esac