build your first basic workflow experimentation #3994

jsundai · 2025-11-13T20:00:42Z

What does this PR do?

https://temporal-documentation-git-tutorial-layout-money-transfe-0fc0c4.preview.thundergun.io/build-your-first-basic-workflow/build-your-first-workflow

Notes to reviewers

files changed include new components for interaction and sdk boxed logos
wip (TODO: make light mode friendly)
aiming for: concise + engaging, dev-to-dev tone, consistent interactions, progressive disclosure.
next iteration: can include sdk box logos

vercel · 2025-11-13T20:00:48Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
temporal-documentation	Ready	Preview, Comment	Jan 20, 2026 8:20pm

static/img/sdks/sdk-box-logos/dotnet.svg

flippedcoder · 2025-12-01T15:51:32Z

A couple of general questions.

Are we adding all of the UI components because they'll be used on future content like this or is it more specific for this guide? It all looks really great, but I think it looks different from the rest of the site and it threw me off at first.
It seemed like this example is already on the learn site. Is this supposed to be migrating the content over or is it supposed to something new?

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

docs/build-your-first-basic-workflow/failure-simulation.mdx

lennessyy

This is gorgeous! Great work. My comments are aimed at user-friendliness but may make it less pretty

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

lennessyy · 2025-12-02T01:01:51Z

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

+id: build-your-first-workflow
+title: Build Your First Workflow
+sidebar_label: "Part 1: Build Your First Workflow"
+hide_table_of_contents: true


i know that the layout is well designed and we could use the vertical space, but i still think this is a long enough tutorial that it'd be beneficial to have the TOC. It's easier for users to make sense of whey are doing in the context of the whole project. Right now, they can't see more than the H2 heading they are in.

brianmacdonald-temporal

I feel like we could use some text explanation for each of the code blocks. Maybe Point out specifically what the workflow is calling, and how that relates to the activities, and point out the Retry Policy details.

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

….mdx Co-authored-by: Milecia McG <47196133+flippedcoder@users.noreply.github.com>

…ated and added light and dark mode reimburse diagram, max width 60

github-actions · 2026-01-15T19:37:58Z

📖 Docs PR preview links

Build your First Basic Workflow
- Part 1: Build Your First Workflow
- Part 2: Failure Simulation

flippedcoder · 2026-01-21T20:47:06Z

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

+The Temporal Application will consist of the following pieces:
+
+1. **A Workflow** written in your programming language of choice and your installed Temporal SDK in that language. A Workflow defines the overall flow of the application.
+2. **An Activity** is a function or method that does specific operation - like withdrawing money, sending an email, or calling an API. Since these operations often depend on external services that can be unreliable, Temporal automatically retries Activities when they fail. 


Suggested change

2. **An Activity** is a function or method that does specific operation - like withdrawing money, sending an email, or calling an API. Since these operations often depend on external services that can be unreliable, Temporal automatically retries Activities when they fail.

2. **An Activity** is a function or method that does a specific operation - like withdrawing money, sending an email, or calling an API. Since these operations often depend on external services that can be unreliable, Temporal automatically retries Activities when they fail.

flippedcoder · 2026-01-21T20:52:35Z

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

+
+</SdkTabs.Java>
+
+<SdkTabs.TypeScript>


Minor thing, but could we have the text wrap button in here like we have on other code blocks for all of these on the page? Example

flippedcoder · 2026-01-21T20:54:13Z

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

+    throw new ApplicationFailure(`Withdrawal failed. Error: ${withdrawErr}`);
+  }
+
+  //Execute the deposit Activity


Suggested change

//Execute the deposit Activity

// Execute the deposit Activity

flippedcoder · 2026-01-21T20:56:18Z

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

+import type { PaymentDetails } from './shared';
+
+// highlight-next-line
+export async function moneyTransfer(details: PaymentDetails): Promise<string> {  // Workflow Definition: an exported async function


Nit: could the // Workflow Definition: an exported async function go above // highlight-next-line to keep it consistent with all the other comments?

flippedcoder · 2026-01-21T20:56:53Z

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

+  let withdrawResult: string;
+  try {
+    // highlight-next-line
+    withdrawResult = await withdraw(details);  // Executes Activity via proxy and waits for result


Nit: could // Executes Activity via proxy and waits for result go above // highlight-next-line to keep it consistent with all the other comments?

flippedcoder · 2026-01-21T21:20:35Z

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

+  </div>
+}>
+
+Now that your Worker is running and polling for tasks, you can start a Workflow Execution.


I might have missed it, but was there somewhere we told the users they would need 3 terminals? It confused me for a second that the first terminal we talked about under the text is Terminal 3.

flippedcoder · 2026-01-21T21:21:43Z

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

+      </SdkTabs>
+    </div>
+    <div style={{marginTop: '2rem', padding: '1rem', background: 'rgba(16, 185, 129, 0.1)', borderRadius: '0.5rem'}}>
+      <strong>Expected Success Output:</strong>


Could we put which terminal this should show in? It looks like Terminal 2.

flippedcoder · 2026-01-21T21:22:22Z

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx

+
+## Check the Temporal Web UI
+
+<SetupStep code={


Nit: could this open in a new tab instead of the docs one?

flippedcoder · 2026-01-21T21:32:52Z

docs/build-your-first-basic-workflow/failure-simulation.mdx

+  const bank = new BankingService('bank2.example.com');
+
+  // Comment out this working line:
+  // return await bank.deposit(details.targetAccount, details.amount, details.referenceId);


It might just be a formatting thing, but this looks different than the repo and the comment/uncomment snippets are in a different order (the good code is on top of the bug code).

flippedcoder · 2026-01-21T21:41:07Z

docs/build-your-first-basic-workflow/failure-simulation.mdx

+Try this advanced scenario of compensating transactions.
+
+
+1. **Modify the retry policy** in `workflows.py` to only retry 1 time


Do we only want to highlight Python here or all the languages?

jsundai added 6 commits October 24, 2025 12:35

starting place

49216ed

first basic workflow python

b383f72

adding components and sdk box logos

47a3a4f

language tabs

eab2cb4

rename for multilanguage

249d92a

text edits

8f112b7

jsundai requested a review from a team as a code owner November 13, 2025 20:00

vercel bot deployed to Preview November 13, 2025 20:01 View deployment

component clean up

435aff1

vercel bot deployed to Preview November 13, 2025 20:27 View deployment

adding custom language order for language tabs

f78d689

vercel bot deployed to Preview November 13, 2025 20:36 View deployment

title and description change

e592d93

vercel bot deployed to Preview November 13, 2025 20:45 View deployment

jsundai changed the title ~~tutorial layout money transfer experimentation~~ build your first basic workflow experimentation Nov 13, 2025

getting started section

c684dea

vercel bot deployed to Preview November 13, 2025 22:47 View deployment

jsundai added 6 commits November 17, 2025 13:45

adding in workflow and activity definition base

302eb07

refining retry policy section and adding each sdk tab

0fa1868

add comments to retry policy code

0186c4b

add base of worker step

15533aa

task queue base by language

e5606d2

add execute the workflow base

ab55d22

vercel bot deployed to Preview November 17, 2025 21:38 View deployment

jsundai added 3 commits November 19, 2025 12:28

adding langauge tabs for crash test

06af7a1

different layout for crash test and friendlier language

938882c

experiment 2 base by sdk

bddc1ce

vercel bot deployed to Preview November 19, 2025 19:34 View deployment

restructured live bug fix section

713e220

flippedcoder reviewed Dec 1, 2025

View reviewed changes

static/img/sdks/sdk-box-logos/dotnet.svg Outdated Show resolved Hide resolved

flippedcoder reviewed Dec 1, 2025

View reviewed changes

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx Outdated Show resolved Hide resolved

flippedcoder reviewed Dec 1, 2025

View reviewed changes

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx Outdated Show resolved Hide resolved

flippedcoder reviewed Dec 1, 2025

View reviewed changes

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx Show resolved Hide resolved

flippedcoder reviewed Dec 1, 2025

View reviewed changes

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx Outdated Show resolved Hide resolved

flippedcoder reviewed Dec 1, 2025

View reviewed changes

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx Outdated Show resolved Hide resolved

flippedcoder reviewed Dec 1, 2025

View reviewed changes

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx Outdated Show resolved Hide resolved

flippedcoder reviewed Dec 1, 2025

View reviewed changes

docs/build-your-first-basic-workflow/failure-simulation.mdx Show resolved Hide resolved

lennessyy reviewed Dec 2, 2025

View reviewed changes

brianmacdonald-temporal reviewed Dec 11, 2025

View reviewed changes

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx Outdated Show resolved Hide resolved

docs/build-your-first-basic-workflow/build-your-first-workflow.mdx Show resolved Hide resolved

jsundai and others added 2 commits January 5, 2026 11:11

Update docs/build-your-first-basic-workflow/build-your-first-workflow…

8c6b2bc

….mdx Co-authored-by: Milecia McG <47196133+flippedcoder@users.noreply.github.com>

Update docs/build-your-first-basic-workflow/build-your-first-workflow…

c375212

….mdx Co-authored-by: Milecia McG <47196133+flippedcoder@users.noreply.github.com>

vercel bot deployed to Preview January 5, 2026 17:15 View deployment

capitalization, uncollapsed, removing sdk box logos

3a316a0

vercel bot deployed to Preview January 5, 2026 19:43 View deployment

replace static reimburse img with built in themedimage component, cre…

a4d89d1

…ated and added light and dark mode reimburse diagram, max width 60

vercel bot deployed to Preview January 5, 2026 20:40 View deployment

changing progress

32219dc

vercel bot deployed to Preview January 7, 2026 15:39 View deployment

Merge branch 'main' into tutorial-layout-money-transfer-experimentation

1a060f1

vercel bot deployed to Preview January 15, 2026 19:39 View deployment

jsundai added 3 commits January 16, 2026 17:18

fix page jumping

f98283b

edits

5d332ca

adding code highlighting and making comments visible

238dc3a

vercel bot had a problem deploying to Preview January 19, 2026 18:45 Failure

feedback

df29cab

vercel bot deployed to Preview January 20, 2026 20:20 View deployment

flippedcoder reviewed Jan 21, 2026

View reviewed changes

	2. An Activity is a function or method that does specific operation - like withdrawing money, sending an email, or calling an API. Since these operations often depend on external services that can be unreliable, Temporal automatically retries Activities when they fail.
	2. An Activity is a function or method that does a specific operation - like withdrawing money, sending an email, or calling an API. Since these operations often depend on external services that can be unreliable, Temporal automatically retries Activities when they fail.

	//Execute the deposit Activity
	// Execute the deposit Activity

		Try this advanced scenario of compensating transactions.


		1. Modify the retry policy in `workflows.py` to only retry 1 time


		</SdkTabs.Java>

		<SdkTabs.TypeScript>

build your first basic workflow experimentation #3994

Are you sure you want to change the base?

build your first basic workflow experimentation #3994

Conversation

jsundai commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Notes to reviewers

Uh oh!

vercel bot commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

flippedcoder commented Dec 1, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lennessyy left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brianmacdonald-temporal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📖 Docs PR preview links

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jsundai commented Nov 13, 2025 •

edited

Loading

vercel bot commented Nov 13, 2025 •

edited

Loading

lennessyy left a comment •

edited

Loading

github-actions bot commented Jan 15, 2026 •

edited

Loading