* Fix Common Gotchas links in language guides
* Fix Standalone Activities links in language guides
---------
Co-authored-by: Brian Strauch <brian@brianstrauch.com>
* Finalize draft for 0011-external-storage
* Fix Python external storage examples
* Add TypeScript external storage guidance
* Address review findings on external storage references
Python:
- Import ClientConfig from temporalio.envconfig, not temporalio.client.
load_client_connect_config() is a staticmethod on the envconfig class;
the temporalio.client.ClientConfig TypedDict has no such member, so the
snippet raised AttributeError. Follow main's env-config convention
(setdefault target_host) from #261.
- Register real Workflow/Activity placeholders. Worker() with empty
workflows and activities raises "At least one activity, Nexus service,
or workflow must be specified", and wrap the setup in async main().
Go:
- Cover the GCS driver (contrib/gcp/gcsdriver + gcssdk), which the SDK
ships and the docs install alongside S3.
- Load client options with envconfig.MustLoadDefaultClientOptions() and
note that Workers inherit External Storage from their Client.
Align coverage across all three languages, each of which was missing
something the others had:
- 50 MiB MaxPayloadSize/max_payload_size ceiling and the matching
anti-pattern (Go, Python).
- Store/Retrieve are not retried within a Task attempt; the Task retries
as a whole, so storage must be idempotent (Go, Python).
- Multi-region durability with CRR + an MRAP ARN (Go, Python).
- Distinct driver names when registering two drivers of the same kind
(Go, Python).
- Codec Server guidance (TypeScript), including that neither the
TypeScript nor Python SDK ships a storage-aware handler.
- Built-in driver behavior sections (concurrency, content-addressed
keys, integrity checks, diagnostics) in Go and Python.
- ctx.Context on the Go driver contexts, mirroring TypeScript's
abortSignal guidance; optional type() override in Python.
Also: standardize the TypeScript Public Preview admonition on the repo's
wording, drop the transplanted `payloadSizeThreshold: 1` anti-pattern
(TypeScript compares >=, so 1 behaves like 0), replace site-relative
plugins-guide links with absolute URLs, refresh the index pointers, and
revert an unrelated whitespace change in the Spring AI reference.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Harden external storage driver examples
* Fix correctness bugs in external storage references
Address code-review findings on the new external storage docs:
- Go: add missing "context" and "log" imports to the S3 driver, GCS
driver, and client/worker setup snippets, which presented complete
import lists but failed to compile.
- Go: add go.temporal.io/sdk/contrib/envconfig to both go get lines; it
is a separate module and is imported by the setup snippet.
- Go: give the local-disk worked example an import block, and introduce
the commonpb alias at its first use in the selector example.
- Go and Python: validate claim data in Retrieve/retrieve so a
hand-crafted reference payload cannot read files outside the store
directory, matching the hardening already applied to Store/store.
- Python: the Worker inherits the Data Converter from its Client and
takes no data_converter argument; the prose said to pass it to both.
Verified by compiling every Go snippet against sdk-go and exercising
both path guards.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Route large-payload triage to the external storage references
The new external storage docs were only reachable from the language
index files, so the paths an agent actually takes when a user hits a
payload limit still sent it to hand-roll the claim-check pattern.
- core/error-reference.md: TMPRL1103 recovery now points at built-in
External Storage before manual reference passing.
- core/gotchas.md: the payload-limit fix notes the SDK does this for you
in Go, Python, and TypeScript.
- core/patterns.md: Large Data Handling leads with the SDK-native
option and scopes the manual pattern to the cases that need it.
Also link the Go external storage sample from the Codec Server section,
matching what the Python reference already does.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: skill-sync[bot] <skill-sync[bot]@users.noreply.github.com>
Co-authored-by: Brian Strauch <brian@brianstrauch.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Use env-config for quick-start connections
* Pass namespace from env-config to TypeScript Workers
NativeConnection carries no namespace, and WorkerOptions defaults to
'default' when it is omitted. With TEMPORAL_NAMESPACE (or a temporal.toml
profile) set, the Worker polled 'default' while the Client used the
configured namespace, so the workflow was never picked up.
Verified against a dev server with a non-default namespace: the previous
snippets left the workflow Running with pollers on 'default'; with
namespace: config.namespace both quick starts complete.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Fix Python reference guidance from issue 256
* Correct Worker Versioning parameter and Build ID references
Split the Python Worker Versioning parameter list into one list per
class. build_id is a field of WorkerDeploymentVersion, not a parameter
of WorkerDeploymentConfig, so listing it alongside version and
use_worker_versioning invited WorkerDeploymentConfig(build_id=...),
which raises TypeError. Also adds the previously missing
default_versioning_behavior parameter.
Drop the claim that a Build ID is "not the legacy compatibility-set
API". A Build ID is an identifier rather than an API, and Build IDs are
used by both the legacy compatibility-set model and the current Worker
Deployment model, so the clause implied the opposite of the intended
disambiguation.
Verified against the temporalio 1.31.0 wheel: WorkerDeploymentConfig
(temporalio/worker/_worker.py) declares version, use_worker_versioning,
and default_versioning_behavior; WorkerDeploymentVersion
(temporalio/common.py) declares deployment_name and build_id.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Apply suggestions from code review
Co-authored-by: Brian Strauch <brian@brianstrauch.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Add TypeScript OpenTelemetry integration docs
Split out from the OpenTelemetry plugins topic (PR #243) so the TypeScript
material can be finalized separately. Adds the TS OTel integration
reference, the Distributed Tracing section in TS observability, and the
TS row in the integrations catalog.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix: align python with ts skill
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Patrik Beqo <patbeqo@gmail.com>
Co-authored-by: Patrik Beqo <patrik.beqo@temporal.io>
* Add Python Braintrust integration reference
Authoring topic 0039-braintrust. Adds references/python/integrations/braintrust.md
grounded in docs/develop/python/integrations/braintrust.mdx covering install,
BraintrustPlugin registration on Client + Worker, wrap_openai, start_span, and
load_prompt with fallback.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* Add TypeScript Braintrust integration reference
Authoring topic 0039-braintrust. Adds references/typescript/integrations/braintrust.md
grounded in the Temporal TS integrations index and the canonical Braintrust-hosted
guide. Covers @braintrust/temporal install, initLogger, and BraintrustTemporalPlugin
registration on Client + Worker. Marks wrapTraced/startSpan/loadPrompt details as
VERIFY since the Temporal docs link out for the TS API surface.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* Add Braintrust rows to integrations catalog
Append Python and TypeScript rows linking to the new Braintrust integration
reference files. Python row notes Public Preview status.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* Finalize draft for 0039-braintrust
* Remove Braintrust familiarity prerequisite
* Use uv add for Braintrust dependency
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: skill-sync[bot] <skill-sync[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Brian Strauch <brian@brianstrauch.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Finalize draft for 0022-opentelemetry-plugins
* Remove legacy TracingInterceptor content from OpenTelemetry docs
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Remove Nexus content from OpenTelemetry docs
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Tie OpenTelemetry tracing into the observability references
Both observability.md files advertised "tracing" but had no tracing
section and never linked to the OTel integration docs. Add a concise
Distributed Tracing (OpenTelemetry) section to each, surface the
trace/log/metric correlation, and cross-link so the OTel <-> observability
relationship is bidirectional. Deep API stays canonical in
integrations/opentelemetry.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Trim TypeScript OpenTelemetry doc to lean style
Mirror the lean, example-driven style now used in the Python OTel doc:
fold the Public API / Constructor options / Span names tables into inline
comments and prose, compress propagator customization to a one-liner, and
keep the log/metric correlation tie-in. Update the observability.md pointer
so it no longer promises tables that were removed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Finalize Python file
* Simplify OpenTelemetry rows in integrations catalog
Reduce both OTel rows to a purpose-only description, dropping mechanism
detail (plugin names, interceptors, sinks, propagation specifics).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Finalize observability files other than code snippets
* finalize python observaibility file
* Finalize TS observability file
* cut correlation
* Move TypeScript OpenTelemetry docs to a separate PR
The TypeScript material needs more work, so split it out (now on branch
feat/ts-otel). This leaves PR #243 scoped to the Python OpenTelemetry
integration only: removes the TS integration reference, reverts the TS
observability tracing section, and drops the TS row from the catalog.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Apply suggestions from code review
Co-authored-by: Donald Pinckney <donald_pinckney@icloud.com>
* Apply suggestion from @donald-pinckney
* Apply suggestion from @donald-pinckney
* Consolidate Python OpenTelemetry docs into observability
Remove the standalone references/python/integrations/opentelemetry.md file
and fold its unique content (Common mistakes, workflow custom-span example)
into the Distributed Tracing section of observability.md. Repoint the
integrations catalog row at the observability section.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: skill-sync[bot] <skill-sync[bot]@users.noreply.github.com>
Co-authored-by: Donald Pinckney <donald.pinckney@temporal.io>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Donald Pinckney <donald_pinckney@icloud.com>
* Finalize draft for 0009-versioned-continue-as-new
* Fix non-Go languages
* Simplify examples, don't give an antipattern!
---------
Co-authored-by: skill-sync[bot] <skill-sync[bot]@users.noreply.github.com>
Co-authored-by: Donald Pinckney <donald.pinckney@temporal.io>
* Finalize draft for 0037-standalone-activities-go
* Update Standalone Activities documentation for Go SDK
Edits throughout Go standalone activities
---------
Co-authored-by: skill-sync[bot] <skill-sync[bot]@users.noreply.github.com>
Co-authored-by: Donald Pinckney <donald.pinckney@temporal.io>
* Add Python standalone activities reference
* Add TypeScript standalone activities reference
* Add .NET standalone activities reference
* Add Java standalone activities reference
* Finalize draft for 0001-standalone-activities
* remove incomplete sections
* Add core page which abstracts out all shared stuff
* Standardize connection logic
* Unify worker setup section across SDK standalone-activity refs
Rename the worker section to "Worker setup & activity registration" in
all four SDK files and lead with a single sentence noting the Activity
is defined and registered exactly as normal. Drop the .NET "Define the
Activity" section so no file repeats how to define an activity, matching
the Python structure.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* re-organize to a LOGICAL structure, not just a flat list of H2 headings.
* finish cleaning up parts other than calling activities
* Get client connection in order
* cleanup of operations content
* Add links
---------
Co-authored-by: skill-sync[bot] <skill-sync[bot]@users.noreply.github.com>
Co-authored-by: Donald Pinckney <donald.pinckney@temporal.io>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Implement planned topic: 0035-dns-resolver-config
Add DNS Resolver Configuration section to references/python/advanced-features.md
documenting temporalio.service.DnsLoadBalancingConfig: the resolution_interval_millis
field, the default classvar, the Client.connect / CloudOperationsClient.connect
kwargs, and the silent mutual-exclusion with HttpConnectProxyConfig. Anchored to
sdk-python v1.27.2 source (the official docs site does not yet cover this class).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* Finalize draft for 0035-dns-resolver-config
* Apply suggestions from code review
Co-authored-by: Donald Pinckney <donald_pinckney@icloud.com>
---------
Co-authored-by: skill-sync[bot] <skill-sync[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Donald Pinckney <donald.pinckney@temporal.io>
Co-authored-by: Donald Pinckney <donald_pinckney@icloud.com>
* Finalize draft for 0032-workflow-streams
* Apply suggestions from code review
Co-authored-by: Donald Pinckney <donald_pinckney@icloud.com>
* Remove the extended example. Can add later if needed.
---------
Co-authored-by: skill-sync[bot] <skill-sync[bot]@users.noreply.github.com>
Co-authored-by: Donald Pinckney <donald.pinckney@temporal.io>
Co-authored-by: Donald Pinckney <donald_pinckney@icloud.com>
* Add integrations catalog and per-language integrations/ layout
Adds references/integrations.md as a single catalog table for third-party
plugins and integrations (one row per integration: language, what it does,
link to a reference file). Reference files live under
references/{language}/integrations/.
Pre-seeds the catalog by moving the existing Spring Boot reference into
the new layout (references/java/integrations/spring-boot.md) and updating
its inbound links.
SKILL.md gains a single 3-line "Third-Party Integrations" section pointing
at the catalog so SKILL.md no longer accrues a line per new integration.
Each language entry-point (java.md, python.md) gets a one-line pointer to
the catalog filtered to its language.
This lets open integration PRs (Spring AI, Google ADK, OpenAI Agents
sandbox) be rebased onto a consistent home: move their reference file
into references/{language}/integrations/ and add one row to
references/integrations.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Drop HTML contribution comment from integrations.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* progress on go
* Go translation workflow completed.
* missed a few spots
* Manual edits
* Address feedback
* Add gotcha about anonymous local activities
* Sample code for payload converter
* clarify sdk protection mechanisms
When a workflow is cancelled mid-saga, compensations must run in a
cancellation-protected scope, otherwise they are immediately cancelled
before they can execute.
- Python: wrap compensation loop in asyncio.shield() so it runs even
when the workflow receives a CancelledError
- TypeScript: wrap compensation loop in CancellationScope.nonCancellable()
so it runs even when the root scope is cancelled (per official docs:
"Cleanup logic must be in a nonCancellable scope")
- TypeScript: also fix compensation registration order — register BEFORE
calling the activity (was already correct in Python)
Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
stevenlai