Skip to content

Commit 1becef9

Browse files
lukekneplukeknep
committed
Updated stable IPs doc
2 parents d2cd016 + a88b600 commit 1becef9

600 files changed

Lines changed: 37177 additions & 18035 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 9 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -26,26 +26,16 @@ jobs:
2626
with:
2727
node-version: '20'
2828

29-
- name: Compute preview base URL
29+
- name: Get preview URL from Vercel comment
3030
id: preview-url
31-
env:
32-
REPO_PREVIEW_BASE_URL: ${{ vars.DOCS_PREVIEW_BASE_URL }}
33-
REPO_PREVIEW_TEMPLATE: ${{ vars.DOCS_PREVIEW_BASE_URL_TEMPLATE }}
34-
run: |
35-
BRANCH_NAME="${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}}"
36-
BRANCH_SLUG=$(echo "$BRANCH_NAME" | tr '[:upper:]' '[:lower:]' | tr -d '_' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//')
37-
38-
if [ -n "$REPO_PREVIEW_BASE_URL" ]; then
39-
BASE_URL="$REPO_PREVIEW_BASE_URL"
40-
elif [ -n "$REPO_PREVIEW_TEMPLATE" ]; then
41-
BASE_URL="${REPO_PREVIEW_TEMPLATE//\{branch\}/$BRANCH_SLUG}"
42-
else
43-
BASE_URL="https://temporal-documentation-git-${BRANCH_SLUG}.preview.thundergun.io"
44-
fi
45-
46-
echo "DOCS_PREVIEW_BASE_URL=$BASE_URL" >> "$GITHUB_ENV"
47-
echo "BRANCH_SLUG=$BRANCH_SLUG" >> "$GITHUB_ENV"
48-
echo "base_url=$BASE_URL" >> "$GITHUB_OUTPUT"
31+
uses: actions/github-script@v7
32+
with:
33+
github-token: ${{ secrets.GITHUB_TOKEN }}
34+
script: |
35+
const { resolvePreviewUrl } = require('./bin/preview-url-from-vercel.js');
36+
const baseUrl = await resolvePreviewUrl({ github, context, core });
37+
core.exportVariable('DOCS_PREVIEW_BASE_URL', baseUrl);
38+
core.setOutput('base_url', baseUrl);
4939
5040
- name: Generate docs preview list
5141
env:

‎.github/workflows/snipsync.yml‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
name: Snipsync
2+
3+
on:
4+
schedule:
5+
- cron: '0 6 * * *' # Daily at 6:00 UTC
6+
workflow_dispatch:
7+
8+
jobs:
9+
snipsync:
10+
name: Sync code snippets
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: write
14+
pull-requests: write
15+
steps:
16+
- name: Generate token
17+
id: generate_token
18+
uses: actions/create-github-app-token@v1
19+
with:
20+
app-id: ${{ secrets.TEMPORAL_CICD_APP_ID }}
21+
private-key: ${{ secrets.TEMPORAL_CICD_PRIVATE_KEY }}
22+
23+
- name: Checkout
24+
uses: actions/checkout@v6
25+
with:
26+
token: ${{ steps.generate_token.outputs.token }}
27+
ref: main
28+
29+
- name: Setup Node
30+
uses: actions/setup-node@v4
31+
with:
32+
node-version: 20
33+
cache: yarn
34+
35+
- name: Install dependencies
36+
run: yarn install --frozen-lockfile
37+
38+
- name: Run snipsync
39+
run: yarn snipsync
40+
41+
- name: Check for changes
42+
id: changes
43+
run: |
44+
if git diff --quiet; then
45+
echo "has_changes=false" >> "$GITHUB_OUTPUT"
46+
else
47+
echo "has_changes=true" >> "$GITHUB_OUTPUT"
48+
fi
49+
50+
- name: Commit and push changes
51+
if: steps.changes.outputs.has_changes == 'true'
52+
run: |
53+
git config user.name "github-actions[bot]"
54+
git config user.email "github-actions[bot]@users.noreply.github.com"
55+
56+
branch_name="snipsync/daily-update"
57+
git checkout -B "$branch_name"
58+
git add docs/
59+
git commit -m "chore: sync code snippets via snipsync"
60+
git push --force origin "$branch_name"
61+
62+
- name: Create or update PR
63+
if: steps.changes.outputs.has_changes == 'true'
64+
env:
65+
GH_TOKEN: ${{ steps.generate_token.outputs.token }}
66+
run: |
67+
branch_name="snipsync/daily-update"
68+
existing_pr=$(gh pr list --head "$branch_name" --state open --json number --jq '.[0].number')
69+
70+
if [ -n "$existing_pr" ]; then
71+
echo "PR #$existing_pr already exists — updated with latest push."
72+
else
73+
gh pr create \
74+
--title "chore: sync code snippets" \
75+
--body "$(cat <<'EOF'
76+
Automated daily sync of code snippets from source repositories via snipsync.
77+
78+
This PR was generated by the [Snipsync workflow](https://github.com/${{ github.repository }}/actions/workflows/snipsync.yml).
79+
EOF
80+
)" \
81+
--head "$branch_name" \
82+
--base "main"
83+
fi

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ test-results
1212
.docusaurus
1313
.cache-loader
1414
temp/
15+
.claude/*
1516

1617
# Misc
1718
.DS_Store
@@ -23,6 +24,8 @@ temp/
2324
.vs
2425
AGENTS.md
2526
CLAUDE.md
27+
.claude/*
28+
.omc
2629

2730
npm-debug.log*
2831
yarn-debug.log*

‎.vscode/settings.json‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +0,0 @@
1-
{
2-
"editor.formatOnSave": true
3-
}

‎COMPONENTS.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,21 @@ Usage:
137137

138138
Images are normally stored in the '/static' folder in `img` or `diagrams`.
139139

140+
### Dark mode images
141+
142+
To provide a separate image for dark mode, use the `srcDark` prop:
143+
144+
```
145+
<CaptionedImage
146+
src="/diagrams/my-diagram.svg"
147+
srcDark="/diagrams/my-diagram-dark.svg"
148+
title="My diagram"
149+
alt="Description of the diagram"
150+
/>
151+
```
152+
153+
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.
154+
140155
### Zooming images
141156

142157
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‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
#!/usr/bin/env node
2+
3+
const MAX_SUBDOMAIN_LENGTH = 63;
4+
const MAX_ATTEMPTS = 18;
5+
const INTERVAL_MS = 10_000;
6+
const PREVIEW_DOMAIN = 'preview.thundergun.io';
7+
8+
function branchToSlug(branchName) {
9+
return branchName
10+
.toLowerCase()
11+
.replace(/_/g, '')
12+
.replace(/[^a-z0-9]/g, '-')
13+
.replace(/-+/g, '-')
14+
.replace(/^-/, '')
15+
.replace(/-$/, '');
16+
}
17+
18+
function buildSubdomain(branchSlug) {
19+
return `temporal-documentation-git-${branchSlug}`;
20+
}
21+
22+
function extractPreviewUrlFromComment(body) {
23+
const match = body.match(/\[vc\]:\s*#[^:]*:(eyJ[A-Za-z0-9+/=]+)/);
24+
if (!match) return null;
25+
26+
const payload = JSON.parse(Buffer.from(match[1], 'base64').toString('utf8'));
27+
return payload.projects?.[0]?.previewUrl || null;
28+
}
29+
30+
async function resolvePreviewUrl({ github, context, core }) {
31+
const branchName = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME;
32+
const branchSlug = branchToSlug(branchName);
33+
const subdomain = buildSubdomain(branchSlug);
34+
35+
if (subdomain.length <= MAX_SUBDOMAIN_LENGTH) {
36+
const baseUrl = `https://${subdomain}.${PREVIEW_DOMAIN}`;
37+
core.info(`Branch name is short enough (${subdomain.length} chars), using constructed URL: ${baseUrl}`);
38+
return baseUrl;
39+
}
40+
41+
core.info(`Subdomain would be ${subdomain.length} chars (exceeds ${MAX_SUBDOMAIN_LENGTH}), polling for Vercel comment...`);
42+
43+
for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
44+
core.info(`Polling for Vercel comment (attempt ${attempt}/${MAX_ATTEMPTS})...`);
45+
const { data: comments } = await github.rest.issues.listComments({
46+
owner: context.repo.owner,
47+
repo: context.repo.repo,
48+
issue_number: context.issue.number,
49+
per_page: 100,
50+
});
51+
52+
const vercelComment = comments.find(
53+
(c) => c.user?.login === 'vercel[bot]' && c.body?.includes('[vc]:'),
54+
);
55+
56+
if (vercelComment) {
57+
const previewUrl = extractPreviewUrlFromComment(vercelComment.body);
58+
if (previewUrl) {
59+
const baseUrl = `https://${previewUrl}`;
60+
core.info(`Found Vercel preview URL: ${baseUrl}`);
61+
return baseUrl;
62+
}
63+
}
64+
65+
if (attempt < MAX_ATTEMPTS) {
66+
await new Promise((resolve) => setTimeout(resolve, INTERVAL_MS));
67+
}
68+
}
69+
70+
core.warning('Vercel comment not found after polling, using constructed URL as fallback (links may be broken for this long branch name)');
71+
return `https://${subdomain}.${PREVIEW_DOMAIN}`;
72+
}
73+
74+
module.exports = { resolvePreviewUrl, branchToSlug, buildSubdomain, extractPreviewUrlFromComment };

‎docs/best-practices/cloud-access-control.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ This approach ensures near-zero-downtime rotation and prevents authentication fa
3737

3838
For mutual TLS (mTLS) implementations, using Let's Encrypt is not recommended, as it is designed primarily for public-facing services and lacks support for internal certificate requirements.
3939

40-
While we are not making a specific product recommendation, there are several valid options for managing certificates. Many organizations choose vendor solutions such as AWS Private CA, Setigo, Microsoft Certification Authority, or DigiCert for their robust integration and lifecycle features. Alternatively, self-signed certificates are a valid and commonly used approach, even in production environments. If you choose to self-sign, tools like [OpenSSL](https://openssl-library.org/), [CFSSL](https://github.com/cloudflare/cfssl), or [step CLI](https://github.com/smallstep/cli) can help generate and manage certificates effectively.
40+
While we are not making a specific product recommendation, there are several valid options for managing certificates. Many organizations choose vendor solutions such as AWS Private CA, Sectigo, Microsoft Certification Authority, or DigiCert for their robust integration and lifecycle features. Alternatively, self-signed certificates are a valid and commonly used approach, even in production environments. If you choose to self-sign, tools like [OpenSSL](https://openssl-library.org/), [CFSSL](https://github.com/cloudflare/cfssl), or [step CLI](https://github.com/smallstep/cli) can help generate and manage certificates effectively.
4141

4242
Select the option that aligns best with your infrastructure, security requirements, and operational needs.
4343

@@ -56,6 +56,6 @@ One convention is to give certificates a common name that matches the namespace.
5656

5757
#### 2. Use Certificate Filters to restrict access when using shared CAs (e.g., `dev` vs `prod`):
5858

59-
Certificate Filters are an additional way of validating using the client certificate presented during client authenticationGive certificates a common name that matches the namespace. This is not a requirement.
59+
Certificate Filters are an additional way of validating using the client certificate presented during client authentication. Give certificates a common name that matches the namespace. This is not a requirement.
6060

6161
If you do this when using the same CA for dev and prod environments, then you can leverage Certificate Filters to prevent access to production.

‎docs/best-practices/cost-optimization.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ See [Spooky Stories: Chilling Temporal Anti-Patterns](https://temporal.io/blog/s
6262
### Large payloads in Workflow History
6363

6464
Passing multi-megabyte payloads through Workflows when external storage (S3, blob storage) is more appropriate.
65-
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.
65+
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.
6666

6767
### Over-optimization at the expense of observability
6868

@@ -137,7 +137,7 @@ For detailed discussion of this tradeoff, see [How many Activities should I use
137137

138138
### Child Workflows vs Activities
139139

140-
[Child Workflows cost 2 Actions](/cloud/actions#child-workflows) compared to an Activity's 1 Action.
140+
[Child Workflows cost 2 Actions](/cloud/actions#workflow) compared to an Activity's 1 Action.
141141
See [Child Workflows documentation](/child-workflows) for detailed comparison of capabilities and use cases.
142142

143143
### Retry Policies
@@ -165,7 +165,7 @@ Refer to this blog post on [Mastering Workflow retry logic for resilient applica
165165
### Local Activities
166166

167167
A [Local Activity](/local-activity#local-activity) is an Activity Execution that executes in the same process as the Workflow Execution that spawns it.
168-
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.
168+
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.
169169
However, there are tradeoffs to converting regular Activities to Local Activities.
170170
For example, if a specific Local Activity fails, *all* of them will be retried together.
171171
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
189189
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.
190190
Batch multiple related attribute updates into single operations to reduce Actions consumed.
191191

192-
See the [Temporal Cloud Action Documentation](/cloud/actions#workflows) for details.
192+
See the [Temporal Cloud Action Documentation](/cloud/actions#workflow) for details.
193193

194194
#### Signal handling
195195

@@ -252,7 +252,7 @@ Alternatively, if you are looking to do analysis on closed Workflow Executions,
252252
### Validation approach
253253

254254
1. **Test in non-production**: Validate functional correctness before production deployment
255-
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
255+
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
256256
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
257257
4. **Continuous review**: Re-evaluate optimization effectiveness quarterly as system evolves
258258

‎docs/best-practices/knowledge-hub.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,12 @@ adopt Temporal independently.
2222

2323
This guide covers what belongs in a knowledge hub, how to communicate it, and how to keep it useful over time.
2424
To bootstrap your knowledge hub, use the
25-
[Temporal Platform Hub](https://kawofong.github.io/temporal-platform-hub/) template as a starting point.
25+
[Temporal Platform Hub](https://go.temporal.io/platform-hub) template as a starting point.
2626

2727
## What belongs in your knowledge hub
2828

2929
Although Temporal itself has [thorough documentation](https://docs.temporal.io/), not all of it applies to your organization or your teams' use cases.
30-
The knolwedge hub distills the documentation into just the specific information your teams need.
30+
The knowledge hub distills the documentation into just the specific information your teams need.
3131
One way to organize the content is according to where developers are in their journey.
3232
The following sample outline shows what sections to include.
3333

@@ -82,7 +82,7 @@ Include the following items in this section:
8282

8383
## Measuring success of your knowledge hub
8484

85-
After you've created your knolwedge hub, establish metrics to measure its effectiveness for your organization.
85+
After you've created your knowledge hub, establish metrics to measure its effectiveness for your organization.
8686
The following table shows example indicators that organizations use to measure the impact of their knowledge hub,
8787
along with realistic before-and-after targets:
8888

@@ -143,4 +143,4 @@ Solicit contributions from application teams through a lightweight process such
143143

144144
## Get started
145145

146-
Start with the [Temporal Platform Hub template](https://kawofong.github.io/temporal-platform-hub/) as your foundation.
146+
Start with the [Temporal Platform Hub template](https://go.temporal.io/platform-hub) as your foundation.

‎docs/best-practices/managing-namespace.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your
106106

107107
If an Authorizer is not set, Temporal uses the `nopAuthority` authorizer that unconditionally allows all API calls.
108108

109-
On Temporal Cloud, [role-based access controls](/cloud/users#namespace-level-permissions) provide namespace-level authorization without custom configuration.
109+
On Temporal Cloud, [role-based access controls](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) provide namespace-level authorization without custom configuration.
110110

111111
### Enable deletion protection (Temporal Cloud only) {#deletion-protection}
112112

0 commit comments

Comments
 (0)