Add workflow to auto-retarget New-Guid docs to 7.7

Checks daily if reference/7.7/ exists upstream.
When found, moves our New-Guid UUID v7 changes from
reference/7.6/ to reference/7.7/ and reverts 7.6.

Related: MicrosoftDocs#12888

Author: SufficientDaikon

.github/workflows/retarget-7.7.yml

@@ -0,0 +1,142 @@
+name: Retarget New-Guid docs to 7.7
+
+on:
+  schedule:
+    # Check daily at 08:00 UTC
+    - cron: '0 8 * * *'
+  workflow_dispatch: # Allow manual trigger
+
+permissions:
+  contents: write
+
+jobs:
+  check-and-retarget:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check if 7.7 folder exists upstream
+        id: check
+        run: |
+          STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+            "https://api.github.com/repos/MicrosoftDocs/PowerShell-Docs/contents/reference/7.7/Microsoft.PowerShell.Utility" \
+            -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}")
+          if [ "$STATUS" = "200" ]; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Exit early if 7.7 not ready
+        if: steps.check.outputs.exists != 'true'
+        run: echo "reference/7.7/ not found upstream yet. Will check again tomorrow."
+
+      - name: Checkout fork
+        if: steps.check.outputs.exists == 'true'
+        uses: actions/checkout@v4
+        with:
+          ref: doc/new-guid-uuid-v7
+          fetch-depth: 0
+
+      - 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
+
+      - name: Check if already retargeted
+        if: steps.check.outputs.exists == 'true'
+        id: already
+        run: |
+          if [ -f "reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md" ]; then
+            echo "done=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "done=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Retarget docs from 7.6 to 7.7
+        if: steps.check.outputs.exists == 'true' && steps.already.outputs.done != 'true'
+        run: |
+          # Rebase onto latest upstream main
+          git rebase upstream/main
+
+          # Get the upstream 7.7 New-Guid.md as base (if it exists), otherwise copy from 7.6
+          if git show upstream/main:reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md > /dev/null 2>&1; then
+            mkdir -p reference/7.7/Microsoft.PowerShell.Utility
+            git show upstream/main:reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md \
+              > reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
+          fi
+
+          # Apply our New-Guid changes to the 7.7 version
+          # Copy our modified 7.6 file as the 7.7 version
+          mkdir -p reference/7.7/Microsoft.PowerShell.Utility
+          cp reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md \
+             reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
+
+          # Update the online version URL from 7.6 to 7.7
+          sed -i 's/view=powershell-7\.6/view=powershell-7.7/g' \
+            reference/7.7/Microsoft.PowerShell.Utility/New-Guid.md
+
+          # Revert the 7.6 file back to upstream state
+          git checkout upstream/main -- reference/7.6/Microsoft.PowerShell.Utility/New-Guid.md
+
+          # Handle What's New: revert 7.6 file, create 7.7 entry if it exists
+          git checkout upstream/main -- reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-76.md
+
+          # If What's New 7.7 file exists upstream, add our entries there
+          WHATS_NEW_77="reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-77.md"
+          if [ -f "$WHATS_NEW_77" ]; then
+            # Add breaking change entry if not already present
+            if ! grep -q "New-Guid.*Version 7" "$WHATS_NEW_77"; then
+              # Insert after "## Breaking changes" or "## Cmdlet improvements" headers
+              python3 - "$WHATS_NEW_77" <<'PYEOF'
+import sys
+path = sys.argv[1]
+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
+  (random). The output format is unchanged. Scripts that depend on fully random GUIDs should use
+  `[guid]::NewGuid()` directly. ([#27033][27033])"""
+
+cmdlet_entry = """- Change `New-Guid` to generate UUID v7 by default using `Guid.CreateVersion7()`
+  ([#27033][27033])"""
+
+link_entry = "[27033]: https://github.com/PowerShell/PowerShell/pull/27033"
+
+# Add entries (simple append approach - manual placement may be needed)
+if '## Breaking changes' in content:
+    content = content.replace('## Breaking changes\n', f'## Breaking changes\n\n{breaking_entry}\n')
+if '## Cmdlet improvements' in content:
+    content = content.replace('## Cmdlet improvements\n', f'## Cmdlet improvements\n\n{cmdlet_entry}\n')
+if link_entry not in content:
+    content = content.rstrip() + '\n' + link_entry + '\n'
+
+with open(path, 'w') as f:
+    f.write(content)
+PYEOF
+            fi
+          fi
+
+          # Stage and commit
+          git add -A
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          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.
+
+          Co-Authored-By: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>"
+
+      - 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
+
+      - name: Post 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 UUID v7 docs from \`reference/7.6/\` to \`reference/7.7/\`." >> "$GITHUB_STEP_SUMMARY"
+          echo "PR #12888 branch has been updated." >> "$GITHUB_STEP_SUMMARY"