Add documentation to GitHub Actions workflow

I've added a bunch of comments to document some of the steps. I've also
removed the unnecessary `persist-credentials: false` option from the
build phase.

1 files changed, 24 insertions, 6 deletions

diff --git a/.github/workflows/lint-build.yaml b/.github/workflows/lint-build.yaml
index e54344fc..1fb6be3e 100644
--- a/.github/workflows/lint-build.yaml
+++ b/.github/workflows/lint-build.yaml
@@ -12,11 +12,19 @@ jobs:
     name: Lint using pre-commit & flake8
     runs-on: ubuntu-latest
     env:
+      # Configure pip to cache dependencies and do a user install
       PIP_NO_CACHE_DIR: false
       PIP_USER: 1
+
+      # Hide the graphical elements from pipenv's output
       PIPENV_HIDE_EMOJIS: 1
-      PIPENV_IGNORE_VIRTUALENVS: 1
       PIPENV_NOSPIN: 1
+
+      # Make sure pipenv does not try reuse an environment it's running in
+      PIPENV_IGNORE_VIRTUALENVS: 1
+
+      # Specify explicit paths for python dependencies and the pre-commit
+      # environment so we know which directories to cache
       PYTHONUSERBASE: ${{ github.workspace }}/.cache/py-user-base
       PRE_COMMIT_HOME: ${{ github.workspace }}/.cache/pre-commit-cache
 
@@ -37,6 +45,12 @@ jobs:
         with:
           python-version: '3.8'
 
+      # This step caches our Python dependencies. To make sure we
+      # only restore a cache when the dependencies, the python version,
+      # the runner operating system, and the dependency location haven't
+      # changed, we create a cache key that is a composite of those states.
+      #
+      # Only when the context is exactly the same, we will restore the cache.
       - name: Python Dependency Caching
         uses: actions/cache@v2
         id: python_cache
@@ -46,12 +60,16 @@ jobs:
           ${{ steps.python.outputs.python-version }}-\
           ${{ hashFiles('./Pipfile', './Pipfile.lock') }}"
 
+      # Install our dependencies if we did not restore a dependency cache
       - name: Install dependencies using pipenv
         if: steps.python_cache.outputs.cache-hit != 'true'
         run: |
           pip install pipenv
           pipenv install --dev --deploy --system
 
+      # This step caches our pre-commit environment. To make sure we
+      # do create a new environment when our pre-commit setup changes,
+      # we create a cache key based on relevant factors.
       - name: Pre-commit Environment Caching
         uses: actions/cache@v2
         with:
@@ -61,12 +79,14 @@ jobs:
           ${{ hashFiles('./.pre-commit-config.yaml') }}"
 
       # We will not run `flake8` here, as we will use a separate flake8
-      # action. As pre-commit does not support user installs, and we don't
-      # really need it, we set PIP_USER=0.
+      # action. As pre-commit does not support user installs, we set
+      # PIP_USER=0 to not do a user install.
       - name: Run pre-commit hooks
         run: export PIP_USER=0; SKIP=flake8 pre-commit run --all-files
 
-      # This step requires `pull_request_target` due to the use of annotations
+      # This step requires `pull_request_target` as we need "write" permissions
+      # to add annotations to the Actions results. A normal `pull_request` trigger
+      # does not get those permissions for security reasons.
       - name: Run flake8
         uses: julianwachholz/flake8-action@v1
         with:
@@ -90,8 +110,6 @@ jobs:
 
       - name: Checkout code
         uses: actions/checkout@v2
-        with:
-          persist-credentials: false
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v1