add clarity for various diff cases

running diff right after new release when there are new changes, running diff between releases, where there are no changes between last run, and when there are no changes from the released code

Author: LFDanLu

.github/workflows/weekly-api-diff.yml

@@ -49,24 +49,33 @@ jobs:
           TODAY=$(date +%Y-%m-%d)
           echo "TODAY=$TODAY" >> $GITHUB_ENV
 
-          # Compare against most recent existing diff BEFORE writing the diff
-          # so that we dont report a diff if we run before a week passes and nothing has changed
-          PREV=$(ls -t snapshots/diffs/*.txt 2>/dev/null | head -1)
-          if [ -n "$PREV" ]; then
-            diff "$PREV" /tmp/diff-current.txt > /tmp/weekly-delta.txt || true
+          CURRENT_PUBLISH=$(git log --grep='^Publish$' --oneline -1 | awk '{print $1}')
+          PREV_PUBLISH=$(cat snapshots/last-publish-hash.txt 2>/dev/null || echo "")
+
+          if [ -n "$PREV_PUBLISH" ] && [ "$CURRENT_PUBLISH" != "$PREV_PUBLISH" ]; then
+            # New release landed so skip comparing to last week, commit fresh as new baseline
+            echo "NEW_RELEASE=true" >> $GITHUB_ENV
           else
-            echo "(first run — no previous diff to compare against)" > /tmp/weekly-delta.txt
+            # Compare against the last diff in the snapshots repo
+            PREV=$(ls -t snapshots/diffs/*.txt 2>/dev/null | head -1)
+            if [ -n "$PREV" ]; then
+              diff "$PREV" /tmp/diff-current.txt > /tmp/weekly-delta.txt || true
+            else
+              echo "(first run — no previous diff to compare against)" > /tmp/weekly-delta.txt
+            fi
           fi
 
-          # Only commit if there are pending API changes and they differ from last week.
-          # If diff-current is empty (release landed), skip commit so the previous
-          # non-empty diff stays as the baseline for next week's comparison.
-          if [ -s /tmp/diff-current.txt ] && [ -s /tmp/weekly-delta.txt ]; then
+          # Commit a diff if there is a new release (fresh baseline), or diff changed from last week
+          # Skip if no difference from last diff (aka no change from last week/last run), or if the diff against the release code is empty
+          NEW_RELEASE="${NEW_RELEASE:-false}"
+          if [ "$NEW_RELEASE" = "true" ] || ([ -s /tmp/diff-current.txt ] && [ -s /tmp/weekly-delta.txt ]); then
             cp /tmp/diff-current.txt snapshots/diffs/$TODAY.txt
             cd snapshots
             git config user.email "github-actions@github.com"
             git config user.name "GitHub Actions"
             git add diffs/$TODAY.txt
+            echo "$CURRENT_PUBLISH" > last-publish-hash.txt
+            git add last-publish-hash.txt
             git diff --cached --quiet || (git commit -m "weekly api diff $TODAY" && git push)
           fi
 
@@ -96,8 +105,22 @@ jobs:
           vs_release_size = os.path.getsize('/tmp/diff-current.txt')
           vs_last_week_size = os.path.getsize('/tmp/weekly-delta.txt') if os.path.exists('/tmp/weekly-delta.txt') else 0
 
-          if vs_release_size == 0 or vs_last_week_size == 0:
-            message = f"📊 Weekly API Diff — {today}\n\nNo API changes vs release baseline this week — either nothing new has landed on main yet, or all pending changes were included in a release."
+          prev_files = sorted(
+            [f for f in __import__('glob').glob(f"{workspace}/snapshots/diffs/*.txt")],
+            key=os.path.getmtime, reverse=True
+          )
+          prev_date = os.path.basename(prev_files[0]).replace('.txt', '') if prev_files else None
+          prev_url = f"https://github.com/{snapshots_repo}/blob/main/diffs/{prev_date}.txt" if prev_date else None
+
+          new_release = os.environ.get('NEW_RELEASE') == 'true'
+
+          if vs_release_size == 0:
+            message = f"📊 Weekly API Diff — {today}\n\nNo API changes detected vs last release — all pending changes have been included in a release."
+          elif vs_last_week_size == 0 and not new_release:
+            prev_ref = f"last diff ({prev_date}): {prev_url}" if prev_date else "last diff"
+            message = f"📊 Weekly API Diff — {today}\n\nNo new API changes since {prev_ref}."
+          elif new_release:
+            message = f"📊 Weekly API Diff — {today}\n\nNew release since last diff — resetting baseline. Full diff vs release: {diff_url}\n\nReact ✅ if changes look expected, or 🚨 if something looks wrong."
           else:
             delta = open('/tmp/weekly-delta.txt').read()[:4000]