Improve the inline documentation and names.

Author: desrosj

.github/workflows/detect-gutenberg-sha-change.yml

@@ -1,7 +1,8 @@
 # Generates a list of changes and a commit message when the pinned gutenberg repository hash changes.
-name: Detect Gutenberg SHA Change
+name: Generate changelog and commit message
 
 on:
+  # This workflow was introduced in WordPress 7.0.
   pull_request:
     branches:
       - trunk
@@ -21,7 +22,12 @@ concurrency:
 permissions: {}
 
 jobs:
-  detect-sha-change:
+  # Detects whether the gutenberg.sha value in the package.json file has changed.
+  #
+  # Performs the following steps:
+  # - Checks out the repository.
+  # - Check if the pinned hash has changed.
+  detect-hash-change:
     name: Detect Gutenberg SHA change
     runs-on: ubuntu-24.04
     if: ${{ github.repository == 'wordpress/wordpress-develop' }}
@@ -58,11 +64,17 @@ jobs:
             echo "The pinned Gutenberg repository hash has not changed: $HEAD_GUTENBERG_SHA"
           fi
 
+  # Generates a list of changes between two specified hashes.
+  #
+  # Performs the following steps:
+  # - Checks out the repository.
+  # - Generates a list of changes.
+  # - Uploads the changelog as an artifact.
   generate-changelog:
     name: Generate a list of changes between the hashes
     runs-on: ubuntu-24.04
-    needs: [ 'detect-sha-change' ]
-    if: ${{ needs.detect-sha-change.outputs.sha_changed == 'true' }}
+    needs: [ 'detect-hash-change' ]
+    if: ${{ needs.detect-hash-change.outputs.sha_changed == 'true' }}
     permissions:
       contents: read
     outputs:
@@ -79,8 +91,8 @@ jobs:
       - name: Generate a list of changes
         id: change-list
         env:
-          BASE_SHA: ${{ needs.detect-sha-change.outputs.base_sha }}
-          HEAD_SHA: ${{ needs.detect-sha-change.outputs.head_sha }}
+          BASE_SHA: ${{ needs.detect-hash-change.outputs.base_sha }}
+          HEAD_SHA: ${{ needs.detect-hash-change.outputs.head_sha }}
         run: |
           git log --reverse --format="- %s" "$BASE_SHA".."$HEAD_SHA" | \
             sed 's|#\([0-9][0-9]*\)|https://github.com/WordPress/gutenberg/pull/\1|g; /github\.com\/WordPress\/gutenberg\/pull/!d' \
@@ -92,25 +104,38 @@ jobs:
             echo "has_changes=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Upload changes artifact
+      - name: Upload changelog as an artifact
         uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           path: changelog.txt
-
           archive: false
+
+  # Drafts a commit message containing a detailed list of changes being merged.
+  #
+  # Performs the following steps:
+  # - Downloads the changelog artifact.
+  # - Builds a commit message.
+  # - Uploads the commit message as an artifact.
   generate-commit-message:
     name: Generate commit message
     runs-on: ubuntu-24.04
-    needs: [ 'detect-sha-change', 'generate-changelog' ]
-    if: ${{ needs.detect-sha-change.outputs.sha_changed == 'true' }}
+    needs: [ 'detect-hash-change', 'generate-changelog' ]
+    if: ${{ needs.detect-hash-change.outputs.sha_changed == 'true' }}
     permissions:
       contents: read
 
     steps:
+      - name: Download changelog artifact
+        if: ${{ needs.generate-changelog.outputs.has_changes == 'true' }}
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: changelog.txt
+          skip-decompress: true
+
       - name: Build commit message
         env:
-          BASE_SHA: ${{ needs.detect-sha-change.outputs.base_sha }}
-          HEAD_SHA: ${{ needs.detect-sha-change.outputs.head_sha }}
+          BASE_SHA: ${{ needs.detect-hash-change.outputs.base_sha }}
+          HEAD_SHA: ${{ needs.detect-hash-change.outputs.head_sha }}
           HAS_CHANGES: ${{ needs.generate-changelog.outputs.has_changes }}
         run: |
           {
@@ -130,7 +155,7 @@ jobs:
             printf 'See #64595, #64393.\n'
           } > commit-message.md
 
-      - name: Upload commit message artifact
+      - name: Upload commit message as an artifact
         uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           path: commit-message.md