.github/tl_packages

@@ -0,0 +1,54 @@
+# The test framework itself
+l3build
+#
+# Required to build plain and LaTeX formats including (u)pLaTeX
+latex-bin
+luahbtex
+platex
+uplatex
+tex
+xetex
+#
+# Then get the rest of required LaTeX
+amsmath
+tools
+#
+# Assuming a 'basic' font set up, metafont is required to avoid
+# warnings with some packages and errors with others
+metafont
+mfware
+#
+# Dependencies for tests that are not auto-resolved
+bibtex
+lualatex-math
+#
+# For the doc target and testing l3doc
+alphalph
+amsfonts
+bookmark
+booktabs
+catchfile
+colortbl
+csquotes
+dvips
+ec
+enumitem
+epstopdf
+epstopdf-pkg
+everysel
+fancyvrb
+hologo
+hyperref
+lipsum
+listings
+makeindex
+mathpazo
+metalogo
+oberdiek
+pgf
+psnfss
+ragged2e
+siunitx
+times
+underscore
+units

.github/workflows/cache.yaml

@@ -0,0 +1,45 @@
+# This workflow makes sure that there is always a cache present for the main branch.
+# This cache can be picked up by all other branches, so it ensures that even new
+# branches and tags don't have to download a complete copy of TeX Live.
+#
+# Since GitHub keeps unused caches for one week, we need to run at least once a week
+# to ensure that the cache always stays around. To avoid timing issues and issues
+# when an update fails for some reason, we run twice per week.
+
+name: Keep TeX Live cache up-to-date
+on:
+  schedule:
+    # Run every tuesday and saturday at 02:48. The time has been chosen at random.
+    - cron: '48 2 * * 2,6'
+
+jobs:
+  cache:
+    runs-on: ubuntu-20.04
+    name: Update TeX Live
+    steps:
+      # 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" and synchronize the other workflow files.
+      - name: Load cache
+        uses: actions/cache@v2
+        with:
+          path: ~/texlive
+          key: texlive-v0-${{ steps.get-id.outputs.id }}
+          restore-keys: texlive-v0-
+      - name: Install TeX Live
+        uses: zauguin/install-texlive@v1
+        with:
+          # List the required TeX Live packages in a separate file to allow reuse in
+          # different workflows.
+          package_file: .github/tl_packages

.github/workflows/deploy.yaml

@@ -0,0 +1,122 @@
+name: Create release
+
+# We create releases for all new tags
+on:
+  push:
+    tags:
+      - "*"
+
+jobs:
+  # The l3build job contains the actual work. This is mostly the same as in main.yaml
+  # and should stay synchronized. Sadly it doesn't seem possible to reuse the instructions at the moment.
+  release:
+    runs-on: ubuntu-20.04
+    name: Build release
+    environment: Release
+    steps:
+      # Boilerplate
+      - name: Checkout repository
+        uses: actions/checkout@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@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 update && sudo apt-get install ghostscript
+      - name: Install TeX Live
+        uses: zauguin/install-texlive@v1
+        with:
+          # List the required TeX Live packages in a separate file to allow reuse in
+          # different workflows.
+          package_file: .github/tl_packages
+      - name: Run l3build
+        run: l3build ctan -q -H --show-log-on-error
+      - name: Archive failed test output
+        if: ${{ failure() }}
+        uses: actions/upload-artifact@v2
+        with:
+          name: testfiles
+          path: build/test*/*.diff
+          # Decide how long to keep the test output artifact:
+          retention-days: 3
+      # Now create the release (this only runs if the previous steps were successful)
+      - name: Create GitHub release
+        uses: ncipollo/release-action@880be3d0a71bc0fa98db60201d2cbdc27324f547
+        id: release
+        with:
+          artifacts: "*.zip"
+          token: ${{ secrets.GITHUB_TOKEN }}
+      # Determine the name of the tag we are working on. Sadly GH Actions only provides
+      # github.ref which has the name prefixed with github.ref and no way to remove a prefix
+      # in normal expressions, so we need an action for that.
+      - name: Get name
+        uses: frabert/replace-string-action@9b62dfe3ae936b1cc380f2421c8ac9e63a4a3e85
+        id: name
+        if: ${{ always() }}
+        with:
+          pattern: "^refs/(?:heads|tags)/"
+          string: ${{ github.ref }}
+          replace-with: ""
+      # While the normal notification job only informs about failed runs, we additionally want to notify about successful releases.
+      - 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@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@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@latex-project.org>
+          # Determine the subject and body of the mail.
+          subject: "Version ${{steps.name.outputs.replaced}} of ${{github.repository}} has been released"
+          body: |
+            The release ${{steps.name.outputs.replaced}} has been created for ${{github.repository}}.
+
+            More information can be found at
+            ${{steps.release.outputs.html_url}}
+      - name: Send failure notification
+        uses: dawidd6/action-send-mail@ceb614a2c5737d913f2d2729e2bcc70ad933382b
+        if: ${{ failure() }}
+        with:
+          server_address: typesetting.eu
+          server_port: 587
+          username: ${{secrets.MAIL_USERNAME}}
+          password: ${{secrets.MAIL_PASSWORD}}
+          to: latex3-commits@tug.org
+          from: LaTeX CI <github@latex-project.org>
+          priority: high
+          # Determine the subject and body of the mail.
+          subject: "Test failure while trying to build release ${{steps.name.outputs.replaced}} in ${{github.repository}}"
+          body: |
+            Test failure for ${{github.repository}}
+            -------------------------------------------------------------
+
+            On tag:           ${{steps.name.outputs.replaced}} (${{github.sha}})
+            Initiated by:     ${{github.actor}}
+            Commit URL:       https://github.com/${{github.repository}}/commit/${{github.sha}}
+            More information: https://github.com/${{github.repository}}/actions/runs/${{github.run_id}}

.github/workflows/main.yaml

@@ -0,0 +1,134 @@
+name: Automated testing
+
+# Currently we run in two situations:
+on:
+  # Whenever someone pushes to a branch in our repo
+  push:
+    branches:
+      - "*"
+  # 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.
+  # For tags we do not run this since we run the release job instead.
+  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: "Test suite"
+            l3build_cmd: l3build check -q -H --show-log-on-error
+            artifact_name: testfiles
+          - name: "Documentation"
+            l3build_cmd: l3build doc -q -H
+            artifact_name: Documentation
+    name: ${{ matrix.name }}
+    steps:
+      # Boilerplate
+      - name: Checkout repository
+        uses: actions/checkout@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@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 update && sudo apt-get install ghostscript
+      - name: Install TeX Live
+        uses: zauguin/install-texlive@v1
+        with:
+          # List the required TeX Live packages in a separate file to allow reuse in
+          # different workflows.
+          package_file: .github/tl_packages
+      - 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@v2
+        with:
+          name: ${{ matrix.artifact_name }}
+          path: build/test*/*.diff
+          # 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@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@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@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@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}}
+            -------------------------------------------------------------
+
+            On branch:        ${{github.ref}} (${{github.sha}})
+            Initiated by:     ${{github.actor}}
+            Commit URL:       https://github.com/${{github.repository}}/commit/${{github.sha}}
+            More information: https://github.com/${{github.repository}}/actions/runs/${{github.run_id}}

.gitignore

@@ -20,3 +20,5 @@ build/*
 *.log
 *.out
 *.toc
+
+.DS_Store