ci: production workflow fixes (#2440)

- Move from yarn cache:clean to yarn nx reset for clarity and to prevent unexpected regressions when changes made to package.json
- Additional comment blocks in production workflow
- Add size change reporting - should add details to the build console if we want to see changes to main
- Remove built asset download for publish site as it's duplicative & add the storybook fallback task to after the site build so it isn't overwritten by the site clean

Author: castastrophe

.github/workflows/build.yml

@@ -105,7 +105,7 @@ jobs:
 
             - name: Reset nx cache to prevent cross-machine errors
               shell: bash
-              run: yarn cache:clean
+              run: yarn nx reset
 
             ## --- BUILD --- ##
             - name: Build components

.github/workflows/production.yml

@@ -1,4 +1,12 @@
 name: Build and verify production
+    # -------------------------------------------------------------
+    # This workflow will build and verify pull requests. It will:
+    # - Build the main branch
+    # - Report on the compiled output
+    # - Run visual regression tests
+    # - Publish the PR branch to Netlify
+    # -------------------------------------------------------------
+
 
 on:
     push:
@@ -16,32 +24,53 @@ defaults:
     run:
         shell: bash
 
-# todo: this could add deploy steps as well
 jobs:
+    # -------------------------------------------------------------
+    # Validate build for various environments
+    # -------------------------------------------------------------
     build:
+        name: Build
         strategy:
             fail-fast: false
             matrix:
                 system:
                     - macos-latest
                     - ubuntu-latest
+                    # - windows-latest
                 node-version:
                     - 18
-        name: Build
         uses: ./.github/workflows/build.yml
         with:
-            ref: ${{ github.sha }}
             system: ${{ matrix.system }}
             node-version: ${{ matrix.node-version }}
         secrets: inherit
 
-    # Run VRT on ALL pushes to main
+    # -------------------------------------------------------------
+    # Report on the compiled assets
+    # -------------------------------------------------------------
+    report:
+        name: Report
+        needs: [build]
+        uses: ./.github/workflows/compare-results.yml
+        with:
+            head-sha: ${{ needs.build.outputs.head-sha }}
+        secrets: inherit
+
+    # -------------------------------------------------------------
+    # RUN VISUAL REGRESSION TESTS --- #
+    # Run VRT on all pushes to main
+    # -------------------------------------------------------------
+
     vrt:
         name: Testing
         needs: [build]
         uses: ./.github/workflows/vrt.yml
         secrets: inherit
 
+    # -------------------------------------------------------------
+    # PUBLISH TO NETLIFY --- #
+    # Publish to netlify by leveraging the previous build and then building the site as well
+    # -------------------------------------------------------------
     publish_site:
         name: Publish
         # The build step ensures we are leveraging the cache for the build
@@ -52,6 +81,7 @@ jobs:
         secrets: inherit
 
     todo_to_issue:
+        name: Add issues for new TODOs
         runs-on: ubuntu-latest
         timeout-minutes: 5
         steps:

.github/workflows/publish-site.yml

@@ -75,31 +75,20 @@ jobs:
 
             - name: Reset nx cache to prevent cross-machine errors
               shell: bash
-              run: yarn cache:clean
+              run: yarn nx reset
 
             ## --- BUILD --- ##
-            - name: Check for built assets
-              continue-on-error: true
-              id: download
-              uses: actions/download-artifact@v4
-              with:
-                  path: |
-                    components/*/dist/**
-                    tokens/dist/**
-                    ui-icons/dist/**
-                  name: ubuntu-latest-node18-compiled-assets-${{ steps.set-SHAs.outputs.head }}
-
-            - name: Build storybook site
-              if: ${{ inputs.storybook-url == '' }}
-              shell: bash
-              run: yarn ci:storybook --output-dir ../dist/preview
-
             - name: Build docs site
               shell: bash
               run: yarn build:site
               env:
                   CHROMATIC_URL: ${{ inputs.storybook-url }}
 
+            - name: Build storybook site
+              if: ${{ inputs.storybook-url == '' }}
+              shell: bash
+              run: yarn ci:storybook --output-dir ../dist/preview
+
             ## --- DEPLOY WEBSITE TO NETLIFY --- ##
             - name: Deploy
               uses: nwtgck/actions-netlify@v2

README.md

@@ -331,7 +331,7 @@ yarn start
 
 This will spin up the local development environment ([Storybook](https://storybook.js.org/docs/web-components/get-started/introduction)). Editing any of the `.css` or the `.stories.js` files in `components/*` will live reload in your browser.
 
-This project is leveraging caching from [Nx](https://nx.dev/) to speed up the build process. If you are seeing unexpected results, you can clear the cache by running `yarn cache:clean`.
+This project is leveraging caching from [Nx](https://nx.dev/) to speed up the build process. If you are seeing unexpected results, you can clear the cache by running `yarn nx reset`.
 
 ### Tasks