prod: June 2nd, 2025

.github/workflows/deploy-docs-prod.yaml

@@ -12,6 +12,10 @@ on:
 
 jobs:
   deploy:
+    if: |
+      github.event_name == 'push' ||
+      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') ||
+      github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/deploy-docs-staging.yaml

@@ -12,6 +12,10 @@ on:
 
 jobs:
   deploy:
+    if: |
+      github.event_name == 'push' ||
+      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') ||
+      github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/merge-main-into-staging.yaml

@@ -39,11 +39,16 @@ jobs:
           title: 'Merge main into staging'
           body: 'Automatically merge main into staging branch.'
 
-      - name: Merge pull request
+      - name: Merge pull request (with retries)
         if: ${{ steps.pr-number.outputs.pull-request-number != '' }}
-        run: gh pr merge --merge --auto "${{ steps.pr-number.outputs.pull-request-number }}"
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          for i in {1..5}; do
+            gh pr merge --merge --auto "${{ steps.pr-number.outputs.pull-request-number }}" && break
+            echo "Merge failed, retrying in 10 seconds ..."
+            sleep 10
+          done
 
       - name: Delete pull request branch
         if: ${{ success() && steps.pr-number.outputs.pull-request-number != '' }}

.github/workflows/vale-lint.yaml

@@ -0,0 +1,140 @@
+name: Vale linter
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review]
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  vale:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v4
+
+    - name: Install Vale
+      run: |
+        wget https://github.com/errata-ai/vale/releases/download/v2.28.0/vale_2.28.0_Linux_64-bit.tar.gz
+        tar -xvzf vale_2.28.0_Linux_64-bit.tar.gz
+        sudo mv vale /usr/local/bin/
+
+    - name: Run Vale
+      id: vale
+      continue-on-error: true
+      run: |
+        vale --output=JSON site/ > vale-report.json || {
+          echo "Vale linting found issues"
+          exit 1
+        }
+
+    - name: Format Vale report for PR comment
+      run: jq . vale-report.json > vale-report-pretty.json
+
+    - name: Upload Vale report as artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: vale-report
+        path: vale-report.json
+        retention-days: 1
+
+    - name: Post Vale results comment
+      uses: actions/github-script@v6
+      with:
+        script: |
+          const runId = context.runId;
+          // Get artifacts for this run
+          const { data: artifacts } = await github.rest.actions.listWorkflowRunArtifacts({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            run_id: runId,
+          });
+          const valeArtifact = artifacts.artifacts.find(a => a.name === 'vale-report');
+          const valeArtifactUrl = valeArtifact
+            ? `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}/artifacts/${valeArtifact.id}`
+            : null;
+
+          // Delete old Vale comments
+          const { data: comments } = await github.rest.issues.listComments({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            issue_number: context.issue.number,
+          });
+
+          for (const comment of comments) {
+            if (comment.user.login === 'github-actions[bot]' && comment.body.includes('## Vale source linter')) {
+              try {
+                console.log(`Deleting Vale comment ${comment.id}`);
+                await github.rest.issues.deleteComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: comment.id,
+                });
+                console.log(`Successfully deleted Vale comment ${comment.id}`);
+              } catch (error) {
+                console.error(`Failed to delete Vale comment ${comment.id}:`, error);
+              }
+            }
+          }
+
+          const fs = require('fs');
+          const report = JSON.parse(fs.readFileSync('vale-report.json', 'utf8'));
+
+          let comment = '## Vale source linter\n\n';
+
+          if (Object.keys(report).length === 0) {
+            comment += `✓ INFO: No writing issues were found ([report](${valeArtifactUrl}))\n\n`;
+          } else {
+            // Build the summary output
+            let summaryOutput = '';
+            let totalIssues = 0;
+            let fileCount = 0;
+
+            for (const [file, issues] of Object.entries(report)) {
+              totalIssues += issues.length;
+              fileCount++;
+
+              // Include first 30 files to keep comment size manageable
+              if (fileCount <= 30) {
+                summaryOutput += `### ${file}\n`;
+                // Only include first 10 issues per file
+                const issuesToShow = issues.slice(0, 10);
+                for (const issue of issuesToShow) {
+                  summaryOutput += `- Line ${issue.Line}: ${issue.Message} (${issue.Severity})\n`;
+                }
+                if (issues.length > 10) {
+                  summaryOutput += `- ... and ${issues.length - 10} more issues\n`;
+                }
+                summaryOutput += '\n';
+              }
+            }
+
+            const workflowRunUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+            comment += `⚠️ WARN: Found **${totalIssues}** issues across **${fileCount}** files — [Check the workflow run](${workflowRunUrl}) or [download the full report](${valeArtifactUrl})\n\n`;
+
+            // Add the summary output in a collapsed section
+            comment += `<details>\n<summary>Show first 30 files with issues</summary>\n\n`;
+            comment += summaryOutput;
+            if (fileCount > 30) {
+              comment += `\n... and ${fileCount - 30} more files with issues\n`;
+            }
+            comment += `\n</details>\n\n`;
+          }
+
+          // Ensure comment doesn't exceed GitHub's limit
+          const MAX_COMMENT_LENGTH = 60000; // Leave some buffer
+          if (comment.length > MAX_COMMENT_LENGTH) {
+            comment = comment.substring(0, MAX_COMMENT_LENGTH) + 
+              `\n\n... (comment truncated due to length) - See full report in artifacts`;
+          }
+
+          github.rest.issues.createComment({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            issue_number: context.issue.number,
+            body: comment
+          });

.github/workflows/validate-docs-site.yaml

@@ -46,7 +46,6 @@ jobs:
           cat render_errors.log;
           exit 1;
           }
-
     # See if site/notebooks/ has updates
     # Checks the current PR branch against the target branch
     - name: Filter changed files
@@ -102,7 +101,7 @@ jobs:
           echo "No warnings or errors detected during Quarto render"
         fi
 
-      # Demo bucket is in us-east-1
+    # Demo bucket is in us-east-1
     - name: Configure AWS credentials
       run: aws configure set aws_access_key_id ${{ secrets.AWS_ACCESS_KEY_ID }} && aws configure set aws_secret_access_key ${{ secrets.AWS_SECRET_ACCESS_KEY }} && aws configure set default.region us-east-1
 
@@ -113,10 +112,31 @@ jobs:
       uses: actions/github-script@v6
       with:
         script: |
-          const url = `https://docs-demo.vm.validmind.ai/pr_previews/${{ github.head_ref }}/index.html`;
+          const previewUrl = `https://docs-demo.vm.validmind.ai/pr_previews/${{ github.head_ref }}/index.html`;
+
+          // Delete old preview comments
+          const { data: comments } = await github.rest.issues.listComments({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            issue_number: context.issue.number,
+          });
+
+          for (const comment of comments) {
+            if (comment.user.login === 'github-actions[bot]' && comment.body.includes('## Validate docs site')) {
+              await github.rest.issues.deleteComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: comment.id,
+              });
+            }
+          }
+
+          let comment = `## Validate docs site\n\n`;
+          comment += `✓ INFO: A live preview of the docs site is available — [Open the preview](${previewUrl})\n\n`;
+
           github.rest.issues.createComment({
             owner: context.repo.owner,
             repo: context.repo.repo,
             issue_number: context.issue.number,
-            body: `A PR preview is available: [Preview URL](${url})`
+            body: comment
           });

.vale.ini

@@ -0,0 +1,13 @@
+StylesPath = .vale/styles
+MinAlertLevel = suggestion
+
+Skips = _*, */_*, plugin/*
+
+Packages = Google
+
+[*.md]
+BasedOnStyles = Vale, Google
+
+[*.qmd]
+BasedOnStyles = Vale, Google
+

.vale/styles/Google/AMPM.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'AM' or 'PM' (preceded by a space)."
+link: "https://developers.google.com/style/word-list"
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}[AP]M\b'
+  - '\d{1,2} ?[ap]m\b'
+  - '\d{1,2} ?[aApP]\.[mM]\.'

.vale/styles/Google/Acronyms.yml

@@ -0,0 +1,64 @@
+extends: conditional
+message: "Spell out '%s', if it's unfamiliar to the audience."
+link: 'https://developers.google.com/style/abbreviations'
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
+# ... with the exception of these:
+exceptions:
+  - API
+  - ASP
+  - CLI
+  - CPU
+  - CSS
+  - CSV
+  - DEBUG
+  - DOM
+  - DPI
+  - FAQ
+  - GCC
+  - GDB
+  - GET
+  - GPU
+  - GTK
+  - GUI
+  - HTML
+  - HTTP
+  - HTTPS
+  - IDE
+  - JAR
+  - JSON
+  - JSX
+  - LESS
+  - LLDB
+  - NET
+  - NOTE
+  - NVDA
+  - OSS
+  - PATH
+  - PDF
+  - PHP
+  - POST
+  - RAM
+  - REPL
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP

.vale/styles/Google/Colons.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: "'%s' should be in lowercase."
+link: 'https://developers.google.com/style/colons'
+nonword: true
+level: warning
+scope: sentence
+tokens:
+  - '(?<!:[^ ]+?):\s[A-Z]'

.vale/styles/Google/Contractions.yml

@@ -0,0 +1,30 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: 'https://developers.google.com/style/contractions'
+level: suggestion
+ignorecase: true
+action:
+  name: replace
+swap:
+  are not: aren't
+  cannot: can't
+  could not: couldn't
+  did not: didn't
+  do not: don't
+  does not: doesn't
+  has not: hasn't
+  have not: haven't
+  how is: how's
+  is not: isn't
+  it is: it's
+  should not: shouldn't
+  that is: that's
+  they are: they're
+  was not: wasn't
+  we are: we're
+  we have: we've
+  were not: weren't
+  what is: what's
+  when is: when's
+  where is: where's
+  will not: won't

.vale/styles/Google/DateFormat.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Use 'July 31, 2016' format, not '%s'."
+link: 'https://developers.google.com/style/dates-times'
+ignorecase: true
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}'
+  - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}'

.vale/styles/Google/Ellipses.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "In general, don't use an ellipsis."
+link: 'https://developers.google.com/style/ellipses'
+nonword: true
+level: warning
+action:
+  name: remove
+tokens:
+  - '\.\.\.'

.vale/styles/Google/EmDash.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Don't put a space before or after a dash."
+link: "https://developers.google.com/style/dashes"
+nonword: true
+level: error
+action:
+  name: edit
+  params:
+    - trim
+    - " "
+tokens:
+  - '\s[—–]\s'
+