Merge branch 'main' into docs/spring-ai-integration

Author: donald-pinckney

.github/workflows/docs-preview-links.yml

@@ -26,26 +26,16 @@ jobs:
         with:
           node-version: '20'
 
-      - name: Compute preview base URL
+      - name: Get preview URL from Vercel comment
         id: preview-url
-        env:
-          REPO_PREVIEW_BASE_URL: ${{ vars.DOCS_PREVIEW_BASE_URL }}
-          REPO_PREVIEW_TEMPLATE: ${{ vars.DOCS_PREVIEW_BASE_URL_TEMPLATE }}
-        run: |
-          BRANCH_NAME="${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}}"
-          BRANCH_SLUG=$(echo "$BRANCH_NAME" | tr '[:upper:]' '[:lower:]' | tr -d '_' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//')
-
-          if [ -n "$REPO_PREVIEW_BASE_URL" ]; then
-            BASE_URL="$REPO_PREVIEW_BASE_URL"
-          elif [ -n "$REPO_PREVIEW_TEMPLATE" ]; then
-            BASE_URL="${REPO_PREVIEW_TEMPLATE//\{branch\}/$BRANCH_SLUG}"
-          else
-            BASE_URL="https://temporal-documentation-git-${BRANCH_SLUG}.preview.thundergun.io"
-          fi
-
-          echo "DOCS_PREVIEW_BASE_URL=$BASE_URL" >> "$GITHUB_ENV"
-          echo "BRANCH_SLUG=$BRANCH_SLUG" >> "$GITHUB_ENV"
-          echo "base_url=$BASE_URL" >> "$GITHUB_OUTPUT"
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { resolvePreviewUrl } = require('./bin/preview-url-from-vercel.js');
+            const baseUrl = await resolvePreviewUrl({ github, context, core });
+            core.exportVariable('DOCS_PREVIEW_BASE_URL', baseUrl);
+            core.setOutput('base_url', baseUrl);
 
       - name: Generate docs preview list
         env:

COMPONENTS.md

@@ -137,6 +137,21 @@ Usage:
 
 Images are normally stored in the '/static' folder in `img` or `diagrams`.
 
+### Dark mode images
+
+To provide a separate image for dark mode, use the `srcDark` prop:
+
+```
+<CaptionedImage
+    src="/diagrams/my-diagram.svg"
+    srcDark="/diagrams/my-diagram-dark.svg"
+    title="My diagram"
+    alt="Description of the diagram"
+/>
+```
+
+When `srcDark` is provided, both images are rendered in the DOM and the browser loads both upfront. CSS toggles visibility based on the active theme, so switching between light and dark mode is instant with no loading delay. When `srcDark` is omitted, the component renders a single image as usual.
+
 ### Zooming images
 
 When images are complex and may not render in a readable fashion on normal monitors, you can enable a minimal form of zooming by setting the `zoom` prop to true:

bin/preview-url-from-vercel.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+const MAX_SUBDOMAIN_LENGTH = 63;
+const MAX_ATTEMPTS = 18;
+const INTERVAL_MS = 10_000;
+const PREVIEW_DOMAIN = 'preview.thundergun.io';
+
+function branchToSlug(branchName) {
+  return branchName
+    .toLowerCase()
+    .replace(/_/g, '')
+    .replace(/[^a-z0-9]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-/, '')
+    .replace(/-$/, '');
+}
+
+function buildSubdomain(branchSlug) {
+  return `temporal-documentation-git-${branchSlug}`;
+}
+
+function extractPreviewUrlFromComment(body) {
+  const match = body.match(/\[vc\]:\s*#[^:]*:(eyJ[A-Za-z0-9+/=]+)/);
+  if (!match) return null;
+
+  const payload = JSON.parse(Buffer.from(match[1], 'base64').toString('utf8'));
+  return payload.projects?.[0]?.previewUrl || null;
+}
+
+async function resolvePreviewUrl({ github, context, core }) {
+  const branchName = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME;
+  const branchSlug = branchToSlug(branchName);
+  const subdomain = buildSubdomain(branchSlug);
+
+  if (subdomain.length <= MAX_SUBDOMAIN_LENGTH) {
+    const baseUrl = `https://${subdomain}.${PREVIEW_DOMAIN}`;
+    core.info(`Branch name is short enough (${subdomain.length} chars), using constructed URL: ${baseUrl}`);
+    return baseUrl;
+  }
+
+  core.info(`Subdomain would be ${subdomain.length} chars (exceeds ${MAX_SUBDOMAIN_LENGTH}), polling for Vercel comment...`);
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    core.info(`Polling for Vercel comment (attempt ${attempt}/${MAX_ATTEMPTS})...`);
+    const { data: comments } = await github.rest.issues.listComments({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      issue_number: context.issue.number,
+      per_page: 100,
+    });
+
+    const vercelComment = comments.find(
+      (c) => c.user?.login === 'vercel[bot]' && c.body?.includes('[vc]:'),
+    );
+
+    if (vercelComment) {
+      const previewUrl = extractPreviewUrlFromComment(vercelComment.body);
+      if (previewUrl) {
+        const baseUrl = `https://${previewUrl}`;
+        core.info(`Found Vercel preview URL: ${baseUrl}`);
+        return baseUrl;
+      }
+    }
+
+    if (attempt < MAX_ATTEMPTS) {
+      await new Promise((resolve) => setTimeout(resolve, INTERVAL_MS));
+    }
+  }
+
+  core.warning('Vercel comment not found after polling, using constructed URL as fallback (links may be broken for this long branch name)');
+  return `https://${subdomain}.${PREVIEW_DOMAIN}`;
+}
+
+module.exports = { resolvePreviewUrl, branchToSlug, buildSubdomain, extractPreviewUrlFromComment };

docs/best-practices/cost-optimization.mdx

@@ -62,7 +62,7 @@ See [Spooky Stories: Chilling Temporal Anti-Patterns](https://temporal.io/blog/s
 ### Large payloads in Workflow History
 
 Passing multi-megabyte payloads through Workflows when external storage (S3, blob storage) is more appropriate.
-Use [compression](/troubleshooting/blob-size-limit-error#why-does-this-error-occur) or the [claim check pattern](https://dataengineering.wiki/Concepts/Software+Engineering/Claim+Check+Pattern) for large data.
+Use [compression](/troubleshooting/blob-size-limit-error#payload-size-limit) or the [claim check pattern](https://dataengineering.wiki/Concepts/Software+Engineering/Claim+Check+Pattern) for large data.
 
 ### Over-optimization at the expense of observability
 
@@ -137,7 +137,7 @@ For detailed discussion of this tradeoff, see [How many Activities should I use
 
 ### Child Workflows vs Activities
 
-[Child Workflows cost 2 Actions](/cloud/actions#child-workflows) compared to an Activity's 1 Action.
+[Child Workflows cost 2 Actions](/cloud/actions#workflow) compared to an Activity's 1 Action.
 See [Child Workflows documentation](/child-workflows) for detailed comparison of capabilities and use cases.
 
 ### Retry Policies
@@ -165,7 +165,7 @@ Refer to this blog post on [Mastering Workflow retry logic for resilient applica
 ### Local Activities
 
 A [Local Activity](/local-activity#local-activity) is an Activity Execution that executes in the same process as the Workflow Execution that spawns it.
-Therefore, multiple Local Activities that run back-to-back only [count as a single billable action](/cloud/actions#activities), whereas each regular Activity counts as a billable action.
+Therefore, multiple Local Activities that run back-to-back only [count as a single billable action](/cloud/actions#activity), whereas each regular Activity counts as a billable action.
 However, there are tradeoffs to converting regular Activities to Local Activities.
 For example, if a specific Local Activity fails, *all* of them will be retried together.
 Review [the docs](/local-activity) or reach out to your account team to learn more.
@@ -189,7 +189,7 @@ Use Regular Activities instead of Local Activities if you require any of the fol
 2. For Search Attributes that must be updated during Workflow Execution, each `UpsertSearchAttributes` call counts as 1 Action regardless of how many attributes are updated.
    Batch multiple related attribute updates into single operations to reduce Actions consumed.
 
-See the [Temporal Cloud Action Documentation](/cloud/actions#workflows) for details.
+See the [Temporal Cloud Action Documentation](/cloud/actions#workflow) for details.
 
 #### Signal handling
 
@@ -252,7 +252,7 @@ Alternatively, if you are looking to do analysis on closed Workflow Executions,
 ### Validation approach
 
 1. **Test in non-production**: Validate functional correctness before production deployment
-2. **Monitor comprehensively**: Leverage the [Usage dashboard](/cloud/actions#usage) in the Cloud UI to track the impact on Actions and Storage after optimizations are made
+2. **Monitor comprehensively**: Leverage the [Usage dashboard](/cloud/actions-usage#usage) in the Cloud UI to track the impact on Actions and Storage after optimizations are made
 3. **Progressive rollout**: Deploy to a small percentage, validate, then expand. Review the [Worker Versioning documentation](/production-deployment/worker-deployments/worker-versioning) to learn about rolling out changes to Workflows
 4. **Continuous review**: Re-evaluate optimization effectiveness quarterly as system evolves