From c5155f16f2c63f49178f5d10d43eb66218b68f44 Mon Sep 17 00:00:00 2001
From: Nathan Melehan <nmelehan@gmail.com>
Date: Mon, 10 May 2021 14:38:24 -0400
Subject: [PATCH] Vale GHA: add comments

---
 .github/workflows/test.yaml | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
index 348cc731241..eb29493a415 100644
--- a/.github/workflows/test.yaml
+++ b/.github/workflows/test.yaml
@@ -39,12 +39,18 @@ jobs:
     - name: Get Changed Files
       id: get_changed_files
       uses: jitterbit/get-changed-files@v1
+      # The continue-on-error parameter is set to true as a
+      # workaround for the `head commit is not ahead of base
+      # commit` error that can appear when the PR branch is
+      # out of date.
       continue-on-error: true
       with:
         format: 'json'
     - name: Install more-utils
       run: sudo apt-get install moreutils
     - name: Select Files in Docs Dir
+      # This action filters the list of added and modified
+      # files to only the files that are in the docs/ directory
       id: select_docs_dir_files
       run: |
         docs_dir_files=$(echo $added_modified |  jq -c '[.[] | select(.|test("^docs/"))]')
@@ -55,6 +61,10 @@ jobs:
         added_modified: ${{ steps.get_changed_files.outputs.added_modified }}
     - name: Vale
       uses: errata-ai/vale-action@v1.3.0
+      # Only run the Vale step if the list of added and modified
+      # files inside the docs directory is not empty. If we don't
+      # add this conditional, the Vale step hangs and never
+      # completes when it is passed the empty array.
       if: ${{ '[]' != steps.select_docs_dir_files.outputs.added_modified }}
       with:
         files: '${{ steps.select_docs_dir_files.outputs.added_modified }}'