[latex3-commits] [git/LaTeX3-latex3-latex2e] develop: Add comments to main.yaml and adjust retention-days (4bf65213)

[Marcel Fabian Krüger]

Repository : https://github.com/latex3/latex2e
On branch  : develop
Link       : https://github.com/latex3/latex2e/commit/4bf65213fea9646404760ae1436202362d5c4046

>---------------------------------------------------------------

commit 4bf65213fea9646404760ae1436202362d5c4046
Author: Marcel Fabian Krüger <tex at 2krueger.de>
Date:   Sun Jul 25 16:23:44 2021 +0200

    Add comments to main.yaml and adjust retention-days


>---------------------------------------------------------------

4bf65213fea9646404760ae1436202362d5c4046
 .github/workflows/main.yaml | 60 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 58 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
index d1c33f36..50946a3f 100644
--- a/.github/workflows/main.yaml
+++ b/.github/workflows/main.yaml
@@ -1,13 +1,30 @@
 name: Automated testing
+
+# Currently we run in two situations:
 on:
+  # Whenever someone pushes to a branch or tag in our repo
   push:
+  # Whenever a pull request is opened, reopened or gets new commits.
   pull_request:
+# This implies that for every push to a local branch in our repo for which a
+# pull request is open this runs twice. But it's important to ensure that pull
+# requests get tested even if their branch comes from a fork.
 
 jobs:
+  # The l3build job contains the actual work. We misuse the matrix mechanism to
+  # create three jobs which only differ in minimal elements.
   l3build:
     runs-on: ubuntu-20.04
     strategy:
       matrix:
+        # include indicates that we want to set explicitly these combinations
+        # and don't want full matrix testing.
+        # "name" is just to make the output more readable.
+        # "l3build_cmd" is the actual command to run
+        # "artifact_name" is which artifact might get generated by this step.
+        # IMPORTANT: artifact_name == "Documentation" is used as a trigger to
+        # generate the artifact from PDF files and not the build directory and
+        # to generate the artifact when the run is successful, not when it fails.
         include:
           - name: "Tests: base"
             l3build_cmd: cd base && l3build check -q --show-log-on-error
@@ -18,26 +35,41 @@ jobs:
           - name: "Documentation"
             l3build_cmd: l3build doc -q -H --show-log-on-error
             artifact_name: Documentation
-            artifact_path: build/doc/*.pdf
     name: ${{matrix.name }}
     steps:
+      # Boilerplate
       - name: Checkout repository
         uses: actions/checkout at v2
+      # GitHub Actions don't regenerate the test if the key doesn't change, so
+      # we integrate a random UUID into the key to keep them different.
+      # DO NOT CHANGE THIS
       - name: Generate unique ID
         id: get-id
         run: |
           echo -n ::set-output name=id::
           cat /proc/sys/kernel/random/uuid
+      # Actually load the cache. Since we never reuse the key, we need restore-keys
+      # to indicate the prefix of our caches. This loads the newest cache with this
+      # prefix in the key.
+      #
+      # If we want to force regeneration of the cache, increase the number after
+      # *both* instances of "texlive-v"
       - name: Load cache
         uses: actions/cache at v2
         with:
           path: ~/texlive
           key: texlive-v0-${{ steps.get-id.outputs.id }}
           restore-keys: texlive-v0-
+      # We need Ghostscript for dvips and XeTeX tests.
       - run: sudo apt-get install ghostscript
       - name: Install TeX Live
         uses: zauguin/install-texlive at v1
         with:
+          # The following list can be altered to change which TeX Live packages to install.
+          # (Technically no YAML comments can appear in there but all lines starting with #
+          # get removed)
+          # There is no technical reason to list every package on a new line, this is only
+          # done for readablity and diff-friendliness.
           packages: |
             # Needed for any use of texlua even if not testing LuaTeX
             luatex
@@ -149,35 +181,59 @@ jobs:
             zref
       - name: Run l3build
         run: ${{ matrix.l3build_cmd }}
+      # Now we create the artifacts: There are two cases where this happens.
+      # 1. If we failed running tests
       - name: Archive failed test output
         if: ${{ matrix.artifact_name != 'Documentation' && failure() }}
         uses: actions/upload-artifact at v2
         with:
           name: ${{ matrix.artifact_name }}
           path: build/test*
-          retention-days: 1
+          # Decide how long to keep the test output artifact:
+          retention-days: 3
+      # 2. If we succeed building documentation
       - name: Archive documentation
         if: ${{ matrix.artifact_name == 'Documentation' && success() }}
         uses: actions/upload-artifact at v2
         with:
           name: ${{ matrix.artifact_name }}
           path: "**/*.pdf"
+          # Decide how long to keep the test output artifact:
+          retention-days: 21
+  # GitHub automatically informs the initiator of any action about the result, but
+  # we additionally want to keep the latex-commits mailing list informed about
+  # test failures.
   notifiy:
     name: Send notifications
     runs-on: ubuntu-20.04
+    # Run after the `l3build` job in order to be able to react to it's output.
     needs: l3build
+    # Only run if the tests failed, we don't want to get notifications for every run.
+    # We don't want information for pull requests since for pull requests from local
+    # branches we already send notifications when the branch test fails and pull requests
+    # from forks can't access the username and password secrets required to send mails.
     if: ${{ failure() && github.event_name != 'pull_request' }}
     steps:
       - name: Send mail
+        # The explicit commit hash ensures that this can't be used by dawidd6 as a
+        # backdoor to execute arbitrary code during our runs.
         uses: dawidd6/action-send-mail at ceb614a2c5737d913f2d2729e2bcc70ad933382b
         with:
+          # Currently using my (Marcel's) mail server for sending mails.
           server_address: typesetting.eu
           server_port: 587
+          # These values can be changed in the repository settings.
           username: ${{secrets.MAIL_USERNAME}}
           password: ${{secrets.MAIL_PASSWORD}}
+          # If we want to send notifications to additional addresses, at them here as
+          # a comma separated list.
           to: latex3-commits at tug.org
+          # The name is arbitrary, but if you want to change the address you need to
+          # coordinate it with the administrator of the mail server to allow the account
+          # to send from the mail address.
           from: LaTeX CI <github at latex-project.org>
           priority: high
+          # Determine the subject and body of the mail.
           subject: "Test failed: ${{github.repository}} (${{github.ref}})"
           body: |
             Test failure for ${{github.repository}}