From 7457490159aa9d0763759240b4161048f2347eca Mon Sep 17 00:00:00 2001
From: Huon Wilson <huon@exoflare.io>
Date: Tue, 5 Nov 2024 09:17:17 +1100
Subject: [PATCH] Make sync_docs failures noisier by always posting a PR (#288)

This makes us more likely to notice problems in the automatic doc
syncing like #284 earlier, by surfacing the failures as PRs, not just
hidden in the actions UI.

The doc syncing usually happens automagically as part of the release
process, in the background. If it fails, this is only visible in two
ways:

- implicitly, in the lack of
<https://github.com/pantsbuild/pantsbuild.org/labels/automation%3Async-docs>-labelled
PR
- by noticing the failure on the actions page:
https://github.com/pantsbuild/pantsbuild.org/actions/workflows/sync_docs.yml

Both of these are easy to miss (very easy to miss that something that
should happen didn't happen, and the actions page is only rarely
visited!). There's no progress updates/reminder about the doc sync, nor
is there a notification on failure.

In practice, we missed failures on the 2.24.x branch for a few releases
(in #284).

This PR adds a "notification" about the failure, by posting the sync PR
unconditionally. The release manager thus gets a notification (about
their review request) and it's visible/easier for others to notice it
too, in the list of PRs. When there's a failure, this PR includes some
extra notes to highlight it.

Examples triggered from this branch:

- successful run (unchanged):
https://github.com/pantsbuild/pantsbuild.org/pull/291
- unsuccessful run (new):
https://github.com/pantsbuild/pantsbuild.org/pull/290

---------

Co-authored-by: Josh Cannon <3956745+thejcannon@users.noreply.github.com>
---
 .github/workflows/sync_docs.yml | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/sync_docs.yml b/.github/workflows/sync_docs.yml
index 757c1e1a..52346d17 100644
--- a/.github/workflows/sync_docs.yml
+++ b/.github/workflows/sync_docs.yml
@@ -95,18 +95,42 @@ jobs:
       # Sync the docs repo
       - run: cp -r pants/docs/docs "pantsbuild.org/${{ steps.get-destination-dir.outputs.DESTINATION_DIR }}"
 
-      # Commit and create a PR
+      # Commit and create a PR.
+      #
+      # This is always performed (even on failure, and even with no code changes), as a mechanism to
+      # surface failures to the reviewer. This workflow is usually triggered by automation in the
+      # background after a release, and it is easy for the release manager to forget to follow up
+      # about the docs (if there's a silent failure).
       - name: Commit changes
+        if: always()
         run: |
           git config --local user.email "pantsbuild+github-automation@gmail.com"
           git config --local user.name "Worker Pants (Pantsbuild GitHub Automation Bot)"
           git checkout -b "automation/sync-${{ inputs.version }}"
           git add -A
-          git commit -m "Update docs site for version ${{ inputs.version }}" -a
+          git commit -m "Update docs site for version ${{ inputs.version }}" -a --allow-empty
           git push -u origin "automation/sync-${{ inputs.version }}"
         working-directory: pantsbuild.org
+      - name: Prepare PR text
+        if: always()
+        run: |
+          touch title-prefix.md
+          echo "Docs from https://github.com/pantsbuild/pants/releases/tag/release_${{ inputs.version }}" > body.md
+      # When the job is failing, add extra info to the PR body:
+      - name: Append failure info
+        if: failure()
+        run: |
+          echo "[FAILURE] " >> title-prefix.md
+          {
+            echo
+            # (would be nice if there was a way to link to this job directly, but the required ID doesn't seem to be available via the context objects)
+            echo "The sync_docs job failed part way through and may need debugging: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+            echo
+            echo "Note: to retry the job, first close this PR and delete its branch."
+          } >> body.md
       - name: Make a PR
-        run: gh pr create --title "Update docs site for version ${{ inputs.version }}" --body "Docs from https://github.com/pantsbuild/pants/releases/tag/release_${{ inputs.version }}" --reviewer "${{ inputs.reviewer || github.actor }}" --label 'automation:sync-docs'
+        if: always()
+        run: gh pr create --title "$(cat ../title-prefix.md)Update docs site for version ${{ inputs.version }}" --body-file=../body.md  --reviewer "${{ inputs.reviewer || github.actor }}" --label 'automation:sync-docs'
         env:
           GH_TOKEN: ${{ secrets.WORKER_PANTS_PR_PAT }}
         working-directory: pantsbuild.org