@suffolklitlab/alkiln 5.10.4 → 5.11.0

package/.github/workflows/github_server.yml

@@ -2,7 +2,6 @@ name: GitHub server installation
 
 on:
   push:
-  # Default "opened", "reopened", "synchronize". "edited" fires when the PR title gets edited, etc.
   pull_request:
   workflow_dispatch:
     inputs:
@@ -14,7 +13,7 @@ on:
         default: false
         type: boolean
         description: 'Show the docker logs while building the GitHub server container. It will also save the docker log artifact. This might show sensitive config information.'
-      #### Developer note: You probably don't need this
+      #### Developer note: You can probably leave this out
       enable_tmate:
         type: boolean
         description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
@@ -24,44 +23,60 @@ on:
 jobs:
 
   github-server-tests:
+    #### Developer note: If under `on` (above) you have both `push` and
+    #### `pull_request`, this avoids running double tests when someone
+    #### on the team makes a pull request
+    # 1: Trigger job on push or dispatch from this repository
+    # 2: Trigger job on pull request from a fork
+    if: (
+          github.event_name != 'pull_request'
+          && ! github.event.pull_request.head.repo.fork
+        ) || (
+          github.event_name == 'pull_request'
+          && github.event.pull_request.head.repo.fork
+        )
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [18.x]
+        node-version: [20.x]
 
+    #### Developer note: You can probably leave out these specific
+    #### environment variables. You may not even need the `env`
+    #### keyword or values at all. See
+    #### https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing#env-vars
     env:
       SECRET_VAR1: secret-var1-value
       SECRET_VAR2: secret-var2-value
       SECRET_FOR_MISSING_FIELD: secret for missing field
       
     steps:
-      #### Developer note: You probably don't need this
       # Place the root directory in this branch to access
       # relative paths to action files
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: ALKiln - Start the isolated temporary docassemble server on GitHub
         id: github_server
-        #### Developer note: you'll need to replace `.` with the path to ALKiln’s
-        #### repo and branch. For example, for version 5, put
-        #### suffolkLITLab/ALKiln/action_for_github_server@v5
-        #### Come back and update this version later if you want the latest
+        #### Developer note: you'll need to replace `uses: ./action_for_github_server`
+        #### with the path to ALKiln’s repository name and branch name. For example,
+        #### for version 5, use the branch name `v5`:
+        #### `uses: suffolkLITLab/ALKiln/action_for_github_server@v5`
         uses: ./action_for_github_server
         with:
-          CONFIG_CONTENTS: "${{ secrets.CONFIG_CONTENTS }}"
-          #### Developer note: Set this to true to show docker logs and
+          #### Developer note: Set this to "true" to show docker logs and
           #### allow ALKiln to create the docker logs output artifact.
           SHOW_DOCKER_OUTPUT: "${{ github.event.inputs.show_docker_output }}"
+          #### Developer note: You can probably leave this out
+          CONFIG_CONTENTS: "${{ secrets.CONFIG_CONTENTS }}"
       - run: echo "ALKiln finished starting the isolated GitHub docassemble server"
         shell: bash
 
-      #### Developer note: You probably don't need this
-      # Optional debugging to explore things like config issues
+      #### Developer note: You can probably leave this out
+      # Optional debugging to explore things like docker issues
       - name: Docker debug tmate session
         if: ${{ github.event.inputs.enable_tmate }}
         uses: mxschmitt/action-tmate@v3
 
-      #### Developer note: You probably don't need this
+      #### Developer note: You can probably leave this out
       - name: Run ALKiln - Env vars for our own tests from server output
         run: |
           echo "USER1_EMAIL=${{ steps.github_server.outputs.DA_ADMIN_EMAIL }}" >> $GITHUB_ENV
@@ -78,18 +93,25 @@ jobs:
 
       - name: "Run ALKiln tests"
         if: ${{ success() }}
-        #### Developer note: you'll need to replace `.` with the path to ALKiln’s
-        #### repo and branch and leave off the trailing `/`
-        #### For example, for version 5 put suffolkLITLab/ALKiln@v5
-        #### Come back and update this version later if you want the latest
+        #### Developer note: you'll need to replace `uses: ./`
+        #### with the path to ALKiln’s repository name and branch name. For example,
+        #### for version 5, use the branch name `v5`: `uses: suffolkLITLab/ALKiln@v5`
         uses: ./
+        #### Developer note: You can probably leave this out
+        env:
+          ALKILN_TAG_EXPRESSION: "${{ (github.event.inputs.tags && format('{0}', github.event.inputs.tags)) || 'not @a11y' }}"
         with:
+          #### Developer note: Required inputs. See
+          #### https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#sandbox-inputs
           SERVER_URL: "${{ steps.github_server.outputs.SERVER_URL }}"
           DOCASSEMBLE_DEVELOPER_API_KEY: "${{ steps.github_server.outputs.DOCASSEMBLE_DEVELOPER_API_KEY }}"
           INSTALL_METHOD: "server"
-          #### Developer note: Useful for temporarily shortening ALKiln tests
-          #### to debug the docker install step
-          #### Use a "tag expression" to specify which tagged tests to run (https://cucumber.io/docs/cucumber/api/#tag-expressions)
-          # ALKILN_TAG_EXPRESSION: @a_tag_expression
-          ALKILN_VERSION: url
+          #### Developer note: See https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#optional-inputs
+          #### You can probably leave this out
+          # Internal: docassemble changes sometimes break @a11y tests. That is
+          # a da problem, not ours. We will trigger these tests manually when we
+          # want to check up on this.
+          ALKILN_TAG_EXPRESSION: $ALKILN_TAG_EXPRESSION
+          #### Developer note: You can probably leave this out
+          # ALKILN_VERSION: url
 

package/.github/workflows/log_code_tests.yml

@@ -0,0 +1,27 @@
+name: "Validate log codes"
+
+# Tests error, warning, info, success, and debug log codes to
+# check for things like mistakes in the numbering of the codes.
+# For example, duplicate code numbers or missing code numbers.
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+
+  log-code-tests:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x]
+
+    name: Validate log codes
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm run codes

package/.github/workflows/playground.yml

@@ -2,7 +2,6 @@ name: Playground installation
 
 on:
   push:
-  # Default: opened, reopened, synchronize. "edited" is not what we want.
   pull_request:
   workflow_dispatch:
     inputs:
@@ -14,18 +13,31 @@ on:
 jobs:
 
   puppeteer-tests:
+    #### Developer note: If under `on` (above) you have both `push` and
+    #### `pull_request`, this avoids running double tests when someone
+    #### editing the repository makes a pull request
+    # 1: Trigger job on push or dispatch from this repository
+    # 2: Trigger job on pull request from a fork
+    if: (
+          github.event_name != 'pull_request'
+          && ! github.event.pull_request.head.repo.fork
+        ) || (
+          github.event_name == 'pull_request'
+          && github.event.pull_request.head.repo.fork
+        )
     runs-on: ubuntu-latest
-
     strategy:
       matrix:
-        node-version: [18.x]
+        node-version: [20.x]
 
     env:
-      #### Developer note: Required
+      #### Developer note: We recommend turning these into environment
+      #### variables before using them as inputs later
       SERVER_URL: ${{ secrets.SERVER_URL }}
       DOCASSEMBLE_DEVELOPER_API_KEY: ${{ secrets.DOCASSEMBLE_DEVELOPER_API_KEY }}
-      #### Developer note: you don't need any of these
-      # Specific to our repo's tests
+
+      #### Developer note: You can probably leave out these specific
+      #### environment variables.
       PLAYGROUND_EMAIL: ${{ secrets.PLAYGROUND_EMAIL }}
       PLAYGROUND_PASSWORD: ${{ secrets.PLAYGROUND_PASSWORD }}
       PLAYGROUND_ID: ${{ secrets.PLAYGROUND_ID }}
@@ -39,25 +51,32 @@ jobs:
 
     name: Run ALKiln tests
     steps:
-      #### Developer note: You probably don't need this
-      # Place the root directory in this branch to access
-      # relative paths to action files
-      - uses: actions/checkout@v3
+      #### Developer note: You can probably leave this out
+      # Place the root directory in this branch to access relative paths to action files
+      - uses: actions/checkout@v4
 
       - name: Pause between triggers
         if: (github.event_name == 'pull_request' && ! github.event.pull_request.head.repo.fork)
         shell: bash
-        run: sleep 30
+        run: sleep 60
 
-      #### Developer note: you'll need to replace `.` with the path to
-      #### the repo and branch and leave off the trailing `/`
-      #### For example suffolkLITLab/ALKiln@v5
+      #### Developer note: you'll need to replace `uses: ./`
+      #### with the path to ALKiln’s repository name and branch name. For example,
+      #### for version 5, use the branch name `v5`: `uses: suffolkLITLab/ALKiln@v5`
       - uses: ./
+        #### Developer note: You can probably leave this out
+        env:
+          ALKILN_TAG_EXPRESSION: "${{ (github.event.inputs.tags && format('{0}', github.event.inputs.tags)) || 'not @a11y' }}"
         with:
+          #### Developer note: Required ALKiln inputs. You can read more at
+          #### https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#githubNyou-inputs
           SERVER_URL: "${{ env.SERVER_URL }}"
           DOCASSEMBLE_DEVELOPER_API_KEY: "${{ env.DOCASSEMBLE_DEVELOPER_API_KEY }}"
-          #### Developer note: Useful for temporarily shortening ALKiln tests
-          #### to debug the docker install step
-          # ALKILN_TAG_EXPRESSION: @a_tag_expression
-          #### Developer note: you probalby don't need this
-          ALKILN_VERSION: url
+          #### Developer note: See https://suffolklitlab.org/docassemble-AssemblyLine-documentation/docs/alkiln/writing/#optional-inputs
+          #### You can probably leave this out
+          # Internal: docassemble changes sometimes break @a11y tests. That is
+          # a da problem, not ours. We will trigger these tests manually when we
+          # want to check up on this.
+          ALKILN_TAG_EXPRESSION: $ALKILN_TAG_EXPRESSION
+          #### Developer note: You can probably leave this out
+          # ALKILN_VERSION: url

package/.github/workflows/unit_tests.yml

@@ -19,8 +19,8 @@ jobs:
         # https://www.shell-tips.com/linux/how-to-format-date-and-time-in-linux-macos-and-bash/#how-to-format-a-date-in-bash
         run: |
           echo "UNIT_TESTS_ARTIFACT_NAME=_alkiln-misc-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm install

package/CHANGELOG.md

@@ -45,6 +45,31 @@ Format:
 
 <!-- ## [Unreleased] -->
 
+## [5.11] - 2024-04-05
+
+### Added
+
+- Add logs for "success" and also non-coded logs for logs that are simply cosmetic - adding a new log to space messages out or show separators.
+
+### Changed
+
+- Error messages now contain error codes. See [#730](https://github.com/SuffolkLITLab/ALKiln/issues/730).
+- Removed extra warning from sources path checking. We currently check a bunch of paths to be flexible and forgiving, so almost every test has been get this warning and it can mislead users. Users do still get an error message if we found no paths at all.
+
+### Internal
+
+- Added: Added script to validate log codes (error, warning, info, success, debug logs). Check for duplicate codes, with some exceptions for actions. Check for missing codes - removed codes are stored in another file, allowing this test to work properly.
+- Added: The above script also reports what the highest log code is (if tests pass), letting the developer see what log code they can add next when they need to add a new log code.
+- Added: Added code validation tests to package.json `test` script.
+- Change: Added and edited documentation comments to the workflow files
+- Change: Avoid running double tests when someone makes a pull request. See [#869](https://github.com/SuffolkLITLab/ALKiln/issues/869).
+- Change: Made sure tests for testing failure all had the same failure tags. Same for warnings.
+- Change: Added "Fail" to the start of the Scenario descriptions of each test that tests failure.
+- Change: Removed "example" code from bottom of ./action.yml page since we have our own file as an example now.
+- Change: Switch a11y tests to only run manually since docassemble changes sometimes cause our tests to fail (which isn't actually relevant to our tests). This may be a temporary fix
+- Fix: Stopped using ALKiln version "url".
+- Fix: Update dependency action versions. See [#844](https://github.com/SuffolkLITLab/ALKiln/issues/844) and [#871](https://github.com/SuffolkLITLab/ALKiln/issues/871).
+
 ## [5.10.4] - 2024-03-25
 
 ### Fixed

package/action.yml

@@ -38,10 +38,10 @@ runs:
   using: "composite"
   steps:
     # Place the root directory in this branch
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     # Set environment variables
-    - name: "ALKiln setup info: Set environment variables"
+    - name: "💡 ALK0023 INFO: Set environment variables"
       # Safe input handling. Avoid evaluating in bash.
       env:
         BRANCH_PATH: ${{ github.ref }}
@@ -51,8 +51,9 @@ runs:
         MAX_SECONDS_FOR_SETUP: ${{ inputs.MAX_SECONDS_FOR_SETUP }}
         SERVER_RELOAD_TIMEOUT_SECONDS: ${{ inputs.SERVER_RELOAD_TIMEOUT_SECONDS }}
         DOCASSEMBLECLI_VERSION: ${{ inputs.DOCASSEMBLECLI_VERSION }}
+      shell: bash
       run: |
-        # ALKiln setup info: Set environment variables
+        # 💡 ALK0023 INFO: Set environment variables
         # Human-readable date/time: https://www.shell-tips.com/linux/how-to-format-date-and-time-in-linux-macos-and-bash/#how-to-format-a-date-in-bash
         echo "ARTIFACT_NAME=alkiln-$(date +'%Y-%m-%d at %Hh%Mm%Ss' -u)UTC" >> $GITHUB_ENV
         echo "REPO_URL=${{ github.server_url }}/${{ github.repository }}" >> $GITHUB_ENV
@@ -66,100 +67,76 @@ runs:
         echo "DOCASSEMBLECLI_VERSION=$DOCASSEMBLECLI_VERSION" >> $GITHUB_ENV
         # Hard-coded internal ALKiln vars
         echo "_ORIGIN=github" >> $GITHUB_ENV
+    - name: "💡 ALK0024 INFO: Confirm environment variables"
       shell: bash
-    - name: "ALKiln setup info: confirm environment variables"
       run: |
-        # ALKiln setup info: confirm environment variables
+        # 💡 ALK0024 INFO: Confirm environment variables
         echo -e "\nALKiln version is $ALKILN_VERSION\nRepo is $REPO_URL\nBranch ref is $BRANCH_PATH\nMAX_SECONDS_FOR_SETUP is $MAX_SECONDS_FOR_SETUP\nSERVER_RELOAD_TIMEOUT_SECONDS is $SERVER_RELOAD_TIMEOUT_SECONDS\n"
-      shell: bash
 
     # Install
-    - name: "ALKiln setup info: Install node packages"
-      uses: actions/setup-node@v3
+    - name: "💡 ALK0025 INFO: Install node packages"
+      uses: actions/setup-node@v4
       with:
         node-version: "18"
-    - name: Install ALKiln directly from npm
+    - name: "💡 ALK0026 INFO: Install ALKiln directly from npm"
+      shell: bash
       run: |
-        # ALKiln setup info: Install ALKiln directly from npm
+        # 💡 ALK0026 INFO: Install ALKiln directly from npm
         npm install -g "@suffolklitlab/alkiln@$ALKILN_VERSION"
-      shell: bash
 
     # Install on playground
 
     # Don't rely on the environment's version of python
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       if: ${{ inputs.INSTALL_METHOD == 'playground' }}
       with:
         python-version: '3.10'
-    - name: "ALKiln: Create a Project and install the package from GitHub"
+    - name: "💡 ALK0027 INFO: Create a Project and install the package from GitHub"
       if: ${{ inputs.INSTALL_METHOD == 'playground' }}
+      shell: bash
       run: |
-        # ALKiln setup info: Create a Project and install the package from GitHub
+        # 💡 ALK0027 INFO: Create a Project and install the package from GitHub
         pip install "docassemblecli==$DOCASSEMBLECLI_VERSION"
         alkiln-setup
-      shell: bash
-    - name: "ALKiln setup ERROR"
-      run: echo -e "\n\n====\nALKiln ERROR - could not create a project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"
+    - name: "😞 ALK0028 ERROR: Unable to create a Project"
       if: ${{ inputs.INSTALL_METHOD == 'playground' && failure() }}
       shell: bash
+      run: |
+        echo -e "\n\n====\n😞 ALK0028 ERROR: Unable to create a Project on your server's testing account or pull your package into it. Check the messages above this line.\n\n"
 
     # Server installations - find folders and save session vars
-    - name: "ALKiln setup info: Install the GitHub package onto the server"
+    - name: "💡 ALK0029 INFO: Install the GitHub package onto the server"
       if: ${{ inputs.INSTALL_METHOD == 'server' }}
-      run: alkiln-server-install
       shell: bash
-    - name: "ALKiln setup ERROR"
-      run: echo -e "\n\n====\nALKiln ERROR - could not install the package on the temporary GitHub docassemble server. Check the steps above this line.\n\n"
+      run: alkiln-server-install
+    - name: "😞 ALK0030 ERROR: Unable to install the package"
       if: ${{ inputs.INSTALL_METHOD == 'server' && failure() }}
       shell: bash
+      run: |
+        echo -e "\n\n====\n😞 ALK0030 ERROR: Unable to install the package on the temporary GitHub docassemble server. Check the steps above this line.\n\n"
 
     # run tests
-    - name: "ALKiln info: Run tests"
+    - name: "💡 ALK0031 INFO: Run tests"
       if: ${{ success() }}
       env:
         ALKILN_TAG_EXPRESSION: ${{ inputs.ALKILN_TAG_EXPRESSION || github.event.inputs.tags && format('{0}', github.event.inputs.tags) }}
-      run: alkiln-run $ALKILN_TAG_EXPRESSION
       shell: bash
+      run: alkiln-run $ALKILN_TAG_EXPRESSION
     
     # on playground, delete project
-    - name: "ALKiln info: Try to delete the project from the playground of the docassemble test account."
+    - name: "💡 ALK0032 INFO: Delete the Project from the Playground"
       if: ${{ always() && inputs.INSTALL_METHOD == 'playground' }}
       run: alkiln-takedown
       shell: bash
     
     # Upload artifacts that subscribers can download on the Actions summary page
-    - name: "ALKiln info: Upload artifacts folder"
+    - name: "💡 ALK0033 INFO: Upload artifacts folder"
       if: ${{ always() }}
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: ${{ env.ARTIFACT_NAME }}
         path: ./alkiln-*
 
-    - run: echo "ALkiln finished running tests"
-      shell: bash
-
-# ##################################
-# # A developer's workflow should look similar to the below.
-# # In place of `uses: suffolkLITLab/ALKiln@v5`, they
-# # might use another version.
-#
-# name: ALKiln v5 tests
-# on:
-#   push:
-#   workflow_dispatch:
-#     inputs:
-#       tags:
-#         description: 'Optional. Use a "tag expression" specify which tagged tests to run. See https://cucumber.io/docs/cucumber/api/#tag-expressions for syntax.'
-#         default: ''
-#
-# jobs:
-#
-#   interview-testing:
-#     runs-on: ubuntu-latest
-#     name: Run interview tests
-#     steps:
-#       - name: Use ALKiln to run tests
-#         uses: suffolkLITLab/ALKiln@v5
-#         with:
-#           SERVER_URL: "${{ secrets.SERVER_URL }}"
-#           DOCASSEMBLE_DEVELOPER_API_KEY: "${{ secrets.DOCASSEMBLE_DEVELOPER_API_KEY }}"
+    - shell: bash
+      run: |
+        echo "💡 ALK0034 INFO: ALkiln finished running tests"