Rewrite retarget workflow: fix all logic bugs, validate locally

SufficientDaikon · SufficientDaikon · commit 39b162f4d3f9 · 2026-03-26T02:05:44.000+02:00
- Fix critical bug: diff after reset --hard produced empty patch
  (now saves upstream 7.6 before reset, diffs against saved copy)
- Fix critical bug: --force-with-lease rejected after reset --hard
  (changed to --force)
- Remove gh pr comment step (GITHUB_TOKEN can't cross orgs)
- Move Python script to temp file (heredoc inside YAML |block
  broke PyYAML linters)
- Remove dead code: whats-new-76 patch was saved but never used
- Remove unused pull-requests:write permission
- Add alternate section header variants for What's New matching
- Validated: YAML parses clean, patch applies to real files,
  Python script tested against mock What's New, all edge cases
  verified under set -euo pipefail
diff --git a/.github/workflows/retarget-7.7.yml b/.github/workflows/retarget-7.7.yml
@@ -2,13 +2,11 @@ name: Retarget New-Guid docs to 7.7
 
 on:
   schedule:
-    # Check daily at 08:00 UTC
     - cron: '0 8 * * *'
-  workflow_dispatch: # Allow manual trigger
+  workflow_dispatch:
 
 permissions:
   contents: write
-  pull-requests: write
 
 jobs:
   check-and-retarget:
@@ -18,10 +16,8 @@ jobs:
       - name: Check if 7.7 folder exists upstream
         id: check
         run: |
-          # Public repo — no auth needed (avoids cross-org token scope issues)
           STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
             "https://api.github.com/repos/MicrosoftDocs/PowerShell-Docs/contents/reference/7.7/Microsoft.PowerShell.Utility")
-          echo "status=$STATUS" >> "$GITHUB_OUTPUT"
           if [ "$STATUS" = "200" ]; then
             echo "exists=true" >> "$GITHUB_OUTPUT"
           else
@@ -36,15 +32,11 @@ jobs:
           ref: doc/new-guid-uuid-v7
           fetch-depth: 0
 
-      - name: Configure git identity
+      - name: Configure git
         if: steps.check.outputs.exists == 'true'
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-
-      - name: Add upstream remote
-        if: steps.check.outputs.exists == 'true'
-        run: |
           git remote add upstream https://github.com/MicrosoftDocs/PowerShell-Docs.git
           git fetch upstream main
 
@@ -64,125 +56,109 @@ jobs:
         run: |
           set -euo pipefail
 
-          # ── 1. Reset branch to upstream main (clean slate, avoids rebase conflicts) ──
-          # Save our modified files first
+          # Save our modified New-Guid and the upstream original before resetting
           cp reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md /tmp/New-Guid-ours.md
-          git diff upstream/main -- reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md \
-            > /tmp/whats-new-76.patch || true
+          git show upstream/main:reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md \
+            > /tmp/New-Guid-upstream-76.md
 
+          # Reset to upstream main (clean slate)
           git reset --hard upstream/main
 
-          # ── 2. Create 7.7 New-Guid.md from our modified version ──
+          # ── Create 7.7 New-Guid.md ──
           mkdir -p reference/7.7/Microsoft.PowerShell.Utility
 
-          # Start with upstream's 7.7 base if it exists, otherwise use our modified file
           if git show upstream/main:reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md > /dev/null 2>&1; then
-            # Upstream has a 7.7 base — use it and apply our changes on top
+            # Upstream has a 7.7 base — extract it and apply our diff on top
             git show upstream/main:reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md \
               > reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
 
-            # Generate a patch from upstream 7.6 → our 7.6 and apply to 7.7
-            git diff upstream/main -- reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md \
-              < /dev/null > /tmp/new-guid.patch || true
-            if [ -s /tmp/new-guid.patch ]; then
-              # Repath the patch from 7.6 to 7.7
-              sed -i 's|reference/7.6/|reference/7.7/|g' /tmp/new-guid.patch
-              git apply --3way /tmp/new-guid.patch || {
-                echo "::warning::Patch apply failed — falling back to direct copy"
+            # Build a unified diff from upstream-7.6 to our-modified-7.6
+            diff -u /tmp/New-Guid-upstream-76.md /tmp/New-Guid-ours.md \
+              > /tmp/our-changes.patch || true
+
+            if [ -s /tmp/our-changes.patch ]; then
+              patch --no-backup-if-mismatch -p0 \
+                reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md \
+                /tmp/our-changes.patch || {
+                echo "::warning::Patch failed — falling back to direct copy"
                 cp /tmp/New-Guid-ours.md reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
               }
             fi
           else
-            # No upstream 7.7 base — copy our modified 7.6 file directly
+            # No upstream 7.7 base — copy our modified file directly
             cp /tmp/New-Guid-ours.md reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
           fi
 
-          # Update version URL: 7.6 → 7.7
+          # Fix version URLs
           sed -i 's/view=powershell-7\.6/view=powershell-7.7/g' \
             reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
 
-          # ── 3. Handle What's New ──
-          # The 7.6 file is already at upstream state (we did reset --hard).
-          # Check if a 7.7 What's New file exists.
+          # ── Handle What's New for 7.7 ──
           WHATS_NEW_77="reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-77.md"
-          if [ -f "$WHATS_NEW_77" ]; then
-            if ! grep -q "New-Guid" "$WHATS_NEW_77"; then
-              python3 <<'PYEOF'
-import sys
-
-path = "reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-77.md"
-with open(path, 'r') as f:
-    content = f.read()
-
-breaking_entry = ("- `New-Guid` now generates Version 7 (time-sortable) UUIDs by default instead of Version 4\n"
-                   "  (random). The output format is unchanged. Scripts that depend on fully random GUIDs should use\n"
-                   "  `[guid]::NewGuid()` directly. ([#27033][27033])")
-
-cmdlet_entry = ("- Change `New-Guid` to generate UUID v7 by default using `Guid.CreateVersion7()`\n"
-                "  ([#27033][27033])")
-
-link_entry = "[27033]: https://github.com/PowerShell/PowerShell/pull/27033"
-
-modified = False
-
-if '## Breaking changes' in content:
-    content = content.replace('## Breaking changes\n', '## Breaking changes\n\n' + breaking_entry + '\n', 1)
-    modified = True
-
-if '## Cmdlet improvements' in content:
-    content = content.replace('## Cmdlet improvements\n', '## Cmdlet improvements\n\n' + cmdlet_entry + '\n', 1)
-    modified = True
-elif '## Updated cmdlets' in content:
-    content = content.replace('## Updated cmdlets\n', '## Updated cmdlets\n\n' + cmdlet_entry + '\n', 1)
-    modified = True
-
-if link_entry not in content:
-    content = content.rstrip() + '\n' + link_entry + '\n'
-    modified = True
-
-if not modified:
-    print("::warning::What's New 7.7 exists but has no recognized section headers. Manual edit needed.")
-    sys.exit(0)
-
-with open(path, 'w') as f:
-    f.write(content)
-print("Updated What's New 7.7 with New-Guid entries.")
-PYEOF
-            fi
-          else
-            echo "::notice::What-s-New-in-PowerShell-77.md does not exist yet. Only New-Guid.md will be included."
+          if [ -f "$WHATS_NEW_77" ] && ! grep -q "New-Guid" "$WHATS_NEW_77"; then
+            # Write the update script to a temp file to avoid YAML quoting issues
+            cat > /tmp/update-whats-new.py << 'PYEOF'
+          import sys
+          path = sys.argv[1]
+          with open(path, 'r') as f:
+              content = f.read()
+          breaking = (
+              '- `New-Guid` now generates Version 7 (time-sortable) UUIDs by default instead of Version 4\n'
+              '  (random). The output format is unchanged. Scripts that depend on fully random GUIDs should use\n'
+              '  `[guid]::NewGuid()` directly. ([#27033][27033])'
+          )
+          cmdlet = (
+              '- Change `New-Guid` to generate UUID v7 by default using `Guid.CreateVersion7()`\n'
+              '  ([#27033][27033])'
+          )
+          link = '[27033]: https://github.com/PowerShell/PowerShell/pull/27033'
+          changed = False
+          for h in ['## Breaking changes', '## Breaking Changes']:
+              if h in content:
+                  content = content.replace(h + '\n', h + '\n\n' + breaking + '\n', 1)
+                  changed = True
+                  break
+          for h in ['## Cmdlet improvements', '## Cmdlet Improvements', '## Updated cmdlets', '## Updated Cmdlets']:
+              if h in content:
+                  content = content.replace(h + '\n', h + '\n\n' + cmdlet + '\n', 1)
+                  changed = True
+                  break
+          if link not in content:
+              content = content.rstrip() + '\n' + link + '\n'
+              changed = True
+          if changed:
+              with open(path, 'w') as f:
+                  f.write(content)
+              print('Updated ' + path)
+          else:
+              print('::warning::No recognized section headers in ' + path + '. Manual edit needed.')
+          PYEOF
+            python3 /tmp/update-whats-new.py "$WHATS_NEW_77"
+          elif [ ! -f "$WHATS_NEW_77" ]; then
+            echo "::notice::What-s-New-in-PowerShell-77.md not found. Only New-Guid.md included."
           fi
 
-          # ── 4. Stage and commit ──
+          # ── Stage and commit ──
           git add reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
-          if [ -f "$WHATS_NEW_77" ]; then
-            git add "$WHATS_NEW_77"
-          fi
+          [ -f "$WHATS_NEW_77" ] && git add "$WHATS_NEW_77" 2>/dev/null || true
 
           git commit -m "Retarget New-Guid UUID v7 docs from 7.6 to 7.7
 
-The 7.7 reference folder is now available upstream.
-Moved New-Guid changes to reference/7.7/ and reverted
-reference/7.6/ to upstream state."
+          The 7.7 reference folder is now available upstream.
+          Moved New-Guid changes to reference/7.7/ and reverted
+          reference/7.6/ to upstream state."
 
       - name: Push changes
         if: steps.check.outputs.exists == 'true' && steps.already.outputs.done != 'true'
-        run: git push origin doc/new-guid-uuid-v7 --force-with-lease
+        run: git push origin doc/new-guid-uuid-v7 --force
 
-      - name: Comment on PR
-        if: steps.check.outputs.exists == 'true' && steps.already.outputs.done != 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          gh pr comment 12888 --repo MicrosoftDocs/PowerShell-Docs --body \
-            "The \`reference/7.7/\` folder is now available upstream. I've retargeted this PR — \`New-Guid.md\` changes now live under \`reference/7.7/\` and the 7.6 file has been reverted to upstream state. Ready for review when convenient."
-
-      - name: Post summary
+      - name: Summary
         if: steps.check.outputs.exists == 'true' && steps.already.outputs.done != 'true'
         run: |
           echo "## Retarget complete" >> "$GITHUB_STEP_SUMMARY"
           echo "" >> "$GITHUB_STEP_SUMMARY"
-          echo "- Moved \`New-Guid.md\` from \`reference/7.6/\` → \`reference/7.7/\`" >> "$GITHUB_STEP_SUMMARY"
-          echo "- Reverted \`reference/7.6/\` to upstream state" >> "$GITHUB_STEP_SUMMARY"
-          echo "- Updated PR branch \`doc/new-guid-uuid-v7\`" >> "$GITHUB_STEP_SUMMARY"
-          echo "- Posted comment on PR #12888" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Moved New-Guid.md from reference/7.6/ to reference/7.7/" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Reverted reference/7.6/ to upstream state" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Force-pushed branch doc/new-guid-uuid-v7" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "Action needed: comment on PR 12888 to mark ready for review." >> "$GITHUB_STEP_SUMMARY"
