chore: workflow documentation cleanup (#4926)

Adds inline documentation to parts of our workflows so it's quicker to get context and know how to update VRT snapshots
adobe · Nov 15, 2024 · 22fc6d6 · 22fc6d6
1 parent 8777a97
commit 22fc6d6
Show file tree

Hide file tree

Showing 18 changed files with 208 additions and 212 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -8,6 +8,10 @@ executors:
         environment:
             NODE_ENV: development
 parameters:
+    # In order to update the VRT baseline images:
+    # 1. Copy the hash of the latest golden images cache from the left sidebar in the VRT preview link (not to be confused with the arbitrary hash in the URL).
+    # 2. Paste the hash in the current_golden_images_hash default parameter below.
+    # 3. Commit this change to the PR branch where the changes exist.
     current_golden_images_hash:
         type: string
         default: 62ecc57a00a4e68cdacbad3ce6f0a205fda2e002

diff --git a/.eslintrc.json b/.eslintrc.json
@@ -1,6 +1,7 @@
 {
     "root": true,
     "plugins": [
+        "@typescript-eslint",
         "notice",
         "@spectrum-web-components",
         "import",
@@ -13,7 +14,7 @@
     },
     "parser": "@typescript-eslint/parser",
     "parserOptions": {
-        "ecmaVersion": 8,
+        "ecmaVersion": 2020,
         "sourceType": "module"
     },
     "rules": {
@@ -70,6 +71,8 @@
         ]
     },
     "extends": [
+        "eslint:recommended",
+        "plugin:@typescript-eslint/recommended",
         "plugin:prettier/recommended",
         "plugin:lit-a11y/recommended",
         "plugin:require-extensions/recommended"

diff --git a/.github/actions/setup-job/action.yml b/.github/actions/setup-job/action.yml
@@ -0,0 +1,15 @@
+name: Setup Job
+description: Common setup for all jobs
+runs:
+    using: 'composite'
+    steps:
+        - name: Setup Node 20
+          uses: actions/setup-node@v4
+          with:
+              node-version: '20'
+              cache: 'yarn'
+              registry-url: 'https://registry.npmjs.org'
+
+        - name: Install dependencies
+          shell: bash
+          run: yarn --frozen-lockfile
diff --git a/.github/workflows/beta-release.yml b/.github/workflows/beta-release.yml
@@ -10,16 +10,11 @@ jobs:
         runs-on: ubuntu-latest
 
         steps:
-            - name: Checkout repository
-              uses: actions/checkout@v3
+            - name: Checkout PR branch
+              uses: actions/checkout@v4
 
-            - name: Set up Node.js
-              uses: actions/setup-node@v3
-              with:
-                  node-version: '20'
-
-            - name: Install dependencies
-              run: yarn install --frozen-lockfile
+            - name: Setup Job and Install Dependencies
+              uses: ./.github/actions/setup-job
 
             - name: Set Git identity
               run: |

diff --git a/.github/workflows/coveralls.yml b/.github/workflows/coveralls.yml
@@ -13,18 +13,11 @@ jobs:
         name: Generate and upload coverage report
         runs-on: ubuntu-latest
         steps:
-            - name: Checkout code
+            - name: Checkout PR branch
               uses: actions/checkout@v4
 
-            - name: Setup Node 20
-              uses: actions/setup-node@v4
-              with:
-                  node-version: '20'
-                  cache: 'yarn'
-                  registry-url: 'https://registry.npmjs.org'
-
-            - name: Install dependencies
-              run: yarn --frozen-lockfile
+            - name: Setup Job and Install Dependencies
+              uses: ./.github/actions/setup-job
 
             - name: Install Playwright
               run: yarn playwright install

diff --git a/.github/workflows/pr-update.yml b/.github/workflows/pr-update.yml
@@ -10,13 +10,12 @@ jobs:
             contents: read
             pull-requests: write
         steps:
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v4
-              with:
-                  cache: yarn
-                  node-version: 20
-            - name: Install dependencies
-              run: yarn install --frozen-lockfile
+            - name: Checkout PR branch
+              uses: actions/checkout@v4
+
+            - name: Setup Job and Install Dependencies
+              uses: ./.github/actions/setup-job
+
               # README: https://github.com/castastrophe/actions-pr-auto-update#auto-update-pull-requests
             - uses: castastrophe/[email protected]
               with:

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -13,15 +13,11 @@ jobs:
         # Run the job if manually triggered or if the commit message includes '#publish' & the check suite has passed
         if: github.event_name == 'workflow_dispatch' || contains(github.event.head_commit.message, '#publish')
         steps:
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v4
-              with:
-                  node-version: '20'
-                  cache: 'yarn'
-                  registry-url: 'https://registry.npmjs.org'
+            - name: Checkout PR branch
+              uses: actions/checkout@v4
 
-            - name: Install dependencies
-              run: yarn --frozen-lockfile
+            - name: Setup Job and Install Dependencies
+              uses: ./.github/actions/setup-job
 
             - name: Generate Docs
               run: yarn docs:ci

diff --git a/.github/workflows/smoke.yml b/.github/workflows/smoke.yml
@@ -9,20 +9,20 @@ jobs:
         timeout-minutes: 60
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v4
-              with:
-                  node-version: 20
-                  cache: 'yarn'
-                  registry-url: 'https://registry.npmjs.org'
+            - name: Checkout PR branch
+              uses: actions/checkout@v4
+
+            - name: Setup Job and Install Dependencies
+              uses: ./.github/actions/setup-job
 
-            - name: Install dependencies
-              run: yarn --frozen-lockfile
             - name: Install Playwright Browsers
               run: npx playwright install --with-deps
+
             - name: Run Playwright tests
               run: npx playwright test projects/documentation/e2e/published.spec.ts
-            - uses: actions/upload-artifact@v4
+
+            - name: Upload Playwright Report
+              uses: actions/upload-artifact@v4
               if: always()
               with:
                   name: playwright-report

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -6,31 +6,25 @@ on:
 
 jobs:
     comment-previews:
-        name: Comments preview URLs
+        name: Create preview URLs and comment
 
-        # We can't currently run benchmarks on PRs from forked repos, because the
-        # tachometer action reports results by posting a comment, and we can't post
-        # comments without a github token.
+        # The job will only run if the pull request is from the same repository.
+        # Benchmarks can't run on PRs from forked repos due to comment posting restrictions without a GitHub token.
         if: github.event.pull_request == null || github.event.pull_request.head.repo.full_name == github.repository
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v4
+            - name: Checkout main
+              uses: actions/checkout@v4
               with:
                   ref: main
 
-            - uses: actions/checkout@v4
+            - name: Checkout PR branch
+              uses: actions/checkout@v4
 
-            - name: Setup Node 20
-              uses: actions/setup-node@v4
-              with:
-                  node-version: '20'
-                  cache: 'yarn'
-                  registry-url: 'https://registry.npmjs.org'
-
-            - name: Install dependencies
-              run: yarn --frozen-lockfile
+            - name: Setup Job and Install Dependencies
+              uses: ./.github/actions/setup-job
 
-            - name: Post Previews
+            - name: Post Previews Comment
               uses: actions/github-script@v7
               with:
                   script: |
@@ -43,28 +37,23 @@ jobs:
         runs-on: ubuntu-22.04
         needs: comment-previews
         steps:
-            - uses: actions/checkout@v4
+            - name: Checkout main
+              uses: actions/checkout@v4
               with:
                   ref: main
 
-            - uses: actions/checkout@v4
-
-            - name: Setup Node 20
-              uses: actions/setup-node@v4
-              with:
-                  node-version: '20'
-                  cache: 'yarn'
-                  registry-url: 'https://registry.npmjs.org'
+            - name: Checkout PR branch
+              uses: actions/checkout@v4
 
-            - name: Install dependencies
-              run: yarn --frozen-lockfile
+            - name: Setup Job and Install Dependencies
+              uses: ./.github/actions/setup-job
 
             - name: Extract branch name
               shell: bash
               run: echo "branch=$(npx slugify-cli ${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}})" >> $GITHUB_OUTPUT
               id: extract_branch
 
-            - name: Lighthouse CI Action
+            - name: Run Lighthouse CI
               id: lighthouse
               uses: treosh/lighthouse-ci-action@v11
               with:
@@ -78,45 +67,41 @@ jobs:
                       https://main--spectrum-web-components.netlify.app/
                       https://${{ steps.extract_branch.outputs.branch }}--spectrum-web-components.netlify.app/
 
-            - name: Post Results
+            - name: Post Lighthouse Results Comment
               uses: actions/github-script@v7
               with:
                   script: |
                       const { buildLighthouseComment } = await import('${{ github.workspace }}/tasks/build-lighthouse-comment.js');
                       const body = buildLighthouseComment(${{ steps.lighthouse.outputs.links }}, ${{ steps.lighthouse.outputs.manifest }}, ${{ steps.lighthouse.outputs.assertionResults }});
                       const { commentOrUpdate } = await import('${{ github.workspace }}/tasks/comment-or-update.js');
                       commentOrUpdate(github, context, '## Lighthouse scores', body);
+
     compare-firefox:
         name: Compare performance to latest release on Firefox
 
-        # We can't currently run benchmarks on PRs from forked repos, because the
-        # tachometer action reports results by posting a comment, and we can't post
-        # comments without a github token.
+        # The job will only run if the pull request is from the same repository.
+        # Benchmarks can't run on PRs from forked repos due to comment posting restrictions without a GitHub token.
         if: github.event.pull_request == null || github.event.pull_request.head.repo.full_name == github.repository
         runs-on: ubuntu-22.04
         steps:
-            - uses: actions/checkout@v4
+            - name: Checkout main
+              uses: actions/checkout@v4
               with:
                   ref: main
 
-            - uses: actions/checkout@v4
+            - name: Checkout PR branch
+              uses: actions/checkout@v4
 
-            - name: Setup Node 20
-              uses: actions/setup-node@v4
-              with:
-                  node-version: '20'
-                  cache: 'yarn'
-                  registry-url: 'https://registry.npmjs.org'
+            - name: Setup Job and Install Dependencies
+              uses: ./.github/actions/setup-job
 
-            - name: Install dependencies
-              run: yarn --frozen-lockfile
-
-            - run: firefox --version
+            - name: Print Firefox version
+              run: firefox --version
 
             - name: Tachometer the changed packages
               run: yarn test:changed --browser=firefox
 
-            - name: Make at least one results file
+            - name: Create a dummy file to ensure at least one results file exists
               run: touch tachometer.firefox-ran.txt
 
             - name: Archive Firefox tachometer results
@@ -130,32 +115,26 @@ jobs:
     compare-chrome:
         name: Compare performance to latest release on Chrome
 
-        # We can't currently run benchmarks on PRs from forked repos, because the
-        # tachometer action reports results by posting a comment, and we can't post
-        # comments without a github token.
+        # The job will only run if the pull request is from the same repository.
+        # Benchmarks can't run on PRs from forked repos due to comment posting restrictions without a GitHub token.
         if: github.event.pull_request == null || github.event.pull_request.head.repo.full_name == github.repository
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v4
+            - name: Checkout main
+              uses: actions/checkout@v4
               with:
                   ref: main
 
-            - uses: actions/checkout@v4
-
-            - name: Setup Node 20
-              uses: actions/setup-node@v4
-              with:
-                  node-version: '20'
-                  cache: 'yarn'
-                  registry-url: 'https://registry.npmjs.org'
+            - name: Checkout PR branch
+              uses: actions/checkout@v4
 
-            - name: Install dependencies
-              run: yarn --frozen-lockfile
+            - name: Setup Job and Install Dependencies
+              uses: ./.github/actions/setup-job
 
             - name: Tachometer the changed packages
               run: yarn test:changed
 
-            - name: Make at least one results file
+            - name: Create a dummy file to ensure at least one results file exists
               run: touch tachometer.chrome-ran.txt
 
             - name: Archive Chrome tachometer results
@@ -167,30 +146,24 @@ jobs:
                       tachometer.chrome-ran.txt
 
     comment-performance:
-        name: Comment performance results
+        name: Comment tachometer performance results
         needs: [compare-chrome, compare-firefox]
 
-        # We can't currently run benchmarks on PRs from forked repos, because the
-        # tachometer action reports results by posting a comment, and we can't post
-        # comments without a github token.
+        # The job will only run if the pull request is from the same repository.
+        # Benchmarks can't run on PRs from forked repos due to comment posting restrictions without a GitHub token.
         if: github.event.pull_request == null || github.event.pull_request.head.repo.full_name == github.repository
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v4
+            - name: Checkout main
+              uses: actions/checkout@v4
               with:
                   ref: main
 
-            - uses: actions/checkout@v4
-
-            - name: Setup Node 20
-              uses: actions/setup-node@v4
-              with:
-                  node-version: '20'
-                  cache: 'yarn'
-                  registry-url: 'https://registry.npmjs.org'
+            - name: Checkout PR branch
+              uses: actions/checkout@v4
 
-            - name: Install dependencies
-              run: yarn --frozen-lockfile
+            - name: Setup Job and Install Dependencies
+              uses: ./.github/actions/setup-job
 
             - name: Retrieve tachometer results archives
               uses: actions/download-artifact@v4
@@ -202,7 +175,7 @@ jobs:
               with:
                   name: tachometer-results-chrome
 
-            - name: Post Performance
+            - name: Post Tachometer Performance Comment
               uses: actions/github-script@v7
               with:
                   script: |