Added documentation to the workflow files available.

.github/workflows/build-dependency-cache.yml

@@ -1,17 +1,21 @@
 ---
 # Creates a cache of the env directory
+# Documentation for the syntax of this file is located
+# https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions
+
+# The workflow name will show up in the action tab on github during execution
+# https://github.com/VOLTTRON/volttron/actions (or if you are pushing to your own fork change the user)
 
 name: cache virtual env
 
+# Check the cache when a push happens to the repository.
 on: [push]
 
 jobs:
   build:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        #ubuntu-16.04
-        #os: [ubuntu-18.04, ubuntu-20.04]
         os: [ubuntu-16.04, ubuntu-18.04, ubuntu-20.04]
         python-version: [3.6, 3.7, 3.8]
     steps:

.github/workflows/pytest-auth.yml

@@ -1,41 +1,58 @@
 ---
-# This workflow is meant as a foundational workflow for running integration/unit tests on the
-# plaform.  For this workflow we are testing the
+# This workflow is meant as a foundational workflow for running integration/unit tests on multiple targeted
+# ubuntu versions with multiple python versions.
 #
-# volttrontesting/testutils directory using pytest.
+# This workflow utilizes the build-dependency-cache workflow which sets up the environment dependencies using
+# bootstrap.py --all
 #
-# This workflow also shows the caching mechanisms available for storage
-# and retrieval of cache for quicker setup of test environments.
 
+# Documentation for the syntax of this file is located
+# https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions
+
+# The workflow name will show up in the action tab on github during execution
+# https://github.com/VOLTTRON/volttron/actions (or if you are pushing to your own fork change the user)
 name: Testing auth marker
+
+# Determine what events are going to trigger a running of the workflow
 on: [push, pull_request]
 
 jobs:
+  # The job named build
   build:
-    runs-on: ${{ matrix.os }}
+    # The strategy allows customization of the build and allows matrixing the version of os and software
+    # https://docs.github.com/en/[email protected]/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstrategy
     strategy:
       fail-fast: false
       matrix:
-        #ubuntu-16.04
-        #os: [ubuntu-18.04, ubuntu-20.04]
-        os: [ubuntu-16.04, ubuntu-18.04, ubuntu-20.04]
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        # Each entry in the os and python-version matrix will be run so for the 3 x 4 there will be 12 jobs run
+        os: [ ubuntu-16.04, ubuntu-18.04, ubuntu-20.04 ]
+        python-version: [ 3.6, 3.7, 3.8, 3.9 ]
+
+    # Run-on determines the operating system available to run on
+    # - At the current time there is only ubuntu machines between 16.04 and 20.04 available
+    # - This uses the matrix os from the strategy above
+    runs-on: ${{ matrix.os }}
+
+    # Each step will be run in order of listing.
     steps:
       # checkout the volttron repository and set current direectory to it
       - uses: actions/checkout@v2
 
+      # setup the python environment for the operating system
       - name: Set up Python ${{matrix.os}} ${{ matrix.python-version }}
         uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
 
-
+      # Attempt to restore the cache from the build-dependency-cache workflow if present then
+      # the output value steps.check_files.outputs.files_exists will be set (see the next step for usage)
       - name: Has restored cache
         id: check_files
         uses: andstor/file-existence-action@v1
         with:
           files: "env/bin/activate"
 
+      # This step is only run if the cache wasn't able to be restored.
       - name: Install dependencies
         if: steps.check_files.outputs.files_exists != 'true'
         run: |
@@ -47,12 +64,14 @@ jobs:
           source env/bin/activate
           pip install -e .
 
+      # Run the specified tests and save the results to a unique file that can be archived for later analysis.
       - name: Run pytest
         run: |
           source env/bin/activate
           pip install -e .
           pytest -m auth -o junit_family=xunit2 --junitxml=output/test-auth-${{matrix.os}}-${{ matrix.python-version }}-results.xml
 
+      # Archive the results from the pytest to storage.
       - name: Archive test results
         uses: actions/upload-artifact@v2
         if: always()

.github/workflows/pytest-testutils.yml

@@ -12,29 +12,36 @@ on: [push, pull_request]
 
 jobs:
   build:
-    runs-on: ${{ matrix.os }}
+    # The strategy allows customization of the build and allows matrixing the version of os and software
+    # https://docs.github.com/en/[email protected]/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstrategy
     strategy:
       fail-fast: false
       matrix:
-        #ubuntu-16.04
-        #os: [ubuntu-18.04, ubuntu-20.04]
-        os: [ubuntu-16.04, ubuntu-18.04, ubuntu-20.04]
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        # Each entry in the os and python-version matrix will be run so for the 3 x 4 there will be 12 jobs run
+        os: [ ubuntu-16.04, ubuntu-18.04, ubuntu-20.04 ]
+        python-version: [ 3.6, 3.7, 3.8, 3.9 ]
+
+    runs-on: ${{ matrix.os }}
+
     steps:
       # checkout the volttron repository and set current direectory to it
       - uses: actions/checkout@v2
 
+      # Attempt to restore the cache from the build-dependency-cache workflow if present then
+      # the output value steps.check_files.outputs.files_exists will be set (see the next step for usage)
       - name: Set up Python ${{matrix.os}} ${{ matrix.python-version }}
         uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
 
+      # Determine if the cache was restored or not.
       - name: Has restored cache
         id: check_files
         uses: andstor/file-existence-action@v1
         with:
           files: "env/bin/activate"
 
+      # if cache wasn't restored then do an installation of the dependencies
       - name: Install dependencies
         if: steps.check_files.outputs.files_exists != 'true'
         run: |
@@ -46,12 +53,14 @@ jobs:
           source env/bin/activate
           pip install -e .
 
+      # Run the specified tests and save the results to a unique file that can be archived for later analysis.
       - name: Run pytest
         run: |
           source env/bin/activate
           pip install -e .
           pytest volttrontesting/testutils -o junit_family=xunit2 --junitxml=output/test-testutils-${{matrix.os}}-${{ matrix.python-version }}-results.xml
 
+      # Archive the results from the pytest to storage.
       - name: Archive test results
         uses: actions/upload-artifact@v2
         if: always()