From a7fcd939daf5a6b3c711b973a8afd601abe90f71 Mon Sep 17 00:00:00 2001
From: Chris Olszewski <chris.olszewski@temporal.io>
Date: Thu, 9 Oct 2025 14:37:27 -0400
Subject: [PATCH 1/3] add patching sample

---
 README.md                         |   2 +-
 patching/README.md                | 142 ++++++++++++++++++++++++++++++
 patching/my_activities.rb         |  19 ++++
 patching/starter.rb               |  26 ++++++
 patching/worker.rb                |  41 +++++++++
 patching/workflow_1_initial.rb    |  18 ++++
 patching/workflow_2_patched.rb    |  25 ++++++
 patching/workflow_3_deprecated.rb |  19 ++++
 patching/workflow_4_complete.rb   |  18 ++++
 9 files changed, 309 insertions(+), 1 deletion(-)
 create mode 100644 patching/README.md
 create mode 100644 patching/my_activities.rb
 create mode 100644 patching/starter.rb
 create mode 100644 patching/worker.rb
 create mode 100644 patching/workflow_1_initial.rb
 create mode 100644 patching/workflow_2_patched.rb
 create mode 100644 patching/workflow_3_deprecated.rb
 create mode 100644 patching/workflow_4_complete.rb

diff --git a/README.md b/README.md
index 783abce..b128408 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@ Prerequisites:
 * [encryption](encryption) - Demonstrates how to make a codec for end-to-end encryption.
 * [env_config](env_config) - Load client configuration from TOML files with programmatic overrides.
 * [message_passing_simple](message_passing_simple) - Simple workflow that accepts signals, queries, and updates.
+* [patching](patching) - Demonstrates how to safely alter a workflow.
 * [polling/infrequent](polling/infrequent) - Implement an infrequent polling mechanism using Temporal's automatic Activity Retry feature.
 * [rails_app](rails_app) - Basic Rails API application using Temporal workflows and activities.
 * [saga](saga) - Using undo/compensation using a very simplistic Saga pattern.
@@ -40,4 +41,3 @@ Prerequisites:
 To check format and test this repository, run:
 
     bundle exec rake
-
diff --git a/patching/README.md b/patching/README.md
new file mode 100644
index 0000000..e49e92e
--- /dev/null
+++ b/patching/README.md
@@ -0,0 +1,142 @@
+# Patching
+
+This sample shows how to safely update a workflow in stages using `Temporalio::Workflow.patch` and `Temporalio::Workflow.deprecate_patch`.
+
+To run, first see [README.md](../README.md) for prerequisites. Then follow the stages below.
+
+## Stage 1
+
+To simulate our initial workflow, start a worker in another terminal
+
+```bash
+  bundle exec ruby worker.rb initial
+```
+
+Now start a workflow:
+
+```bash
+  bundle exec ruby starter.rb start initial-id
+```
+
+This will output `Started workflow with id initial-id`.
+
+Now query the workflow:
+
+```bash
+  bundle exec ruby starter.rb query initial-id
+```
+
+This will output `Query result for id initial-id: pre-patch`
+
+## Stage 2
+
+This stage is for needing to run old and new workflows at the same time.
+To simulate our patched workflow, stop the worker from before and start it again with the patched workflow:
+
+```bash
+  bundle exec ruby worker.rb patched
+```
+
+Now let's start another workflow with this patched code:
+
+```bash
+  bundle exec ruby starter.rb start patched-id
+```
+
+This will output `Started workflow with id patched-id-workflow-id`.
+
+Now query the old workflow that's still running:
+
+```bash
+  bundle exec starter.rb query initial-id
+```
+
+This will output "Query result for id initial-id: pre-patch" since it is pre-patch.
+
+But if we execute a query against the new code:
+
+```bash
+  bundle exec starter.rb query patched-id
+```
+
+We get "Query result for id patched-id: post-patch".
+
+This is how old workflow code can take old paths and new workflow code can take new paths.
+
+## Stage 3
+
+Once we know that all workflows that started with the initial code from "Stage 1" are no longer running,
+we don't need the patch so we can deprecate it.
+To use the patch deprecated workflow, stop the worker from before and start it again with:
+
+```bash
+  bundle exec ruby worker.rb deprecated
+```
+
+Querying the initial workflow should error now.
+
+```bash
+  bundle exec ruby starter.rb query initial-id
+```
+
+Throws an error: `[TMPRL1100] Nondeterminism error: Activity type of scheduled event 'PrePatch' does not match activity type of activity command 'PostPatch'`
+
+All workflows in "Stage 2" and any new workflows can be queried.
+
+Now let's start another workflow with this patch deprecated code:
+
+```bash
+  bundle exec ruby starter.rb start deprecated-id
+```
+
+This will output `Started workflow with id deprecated-id`.
+Now query the patched workflow from "Stage 2"
+
+```bash
+  bundle exec ruby starter.rb query patched-id
+```
+
+This will output "Query result for id patched-id: post-patch".
+
+And if we execute a query against the latest workflow:
+
+```bash
+  bundle exec ruby starter.rb query deprecated-id
+```
+
+As expected, this will output "Query result for id deprecated-id: post-patch".
+
+## Stage 4
+
+Once we know we don't even have any workflows running on "Stage 2" or before (i.e. the workflow with the patch with both code paths), we can just remove the patch deprecation altogether.
+To use the patch complete workflow, stop the workflow from before and start it again with:
+
+```bash
+  bundle exec ruby worker.rb complete
+```
+
+All workflows in "Stage 3" and any new workflows will work.
+Now let's start another workflow with this patch complete code:
+
+```bash
+  bundle exec ruby starter.rb start complete-id
+```
+
+Now query the patch deprecated workflow that's still running:
+
+```bash
+  bundle exec ruby starter.rb query deprecated-id
+```
+
+This will output "Query result for id deprecated-id: post-patch".
+
+And if we execute a query against the latest workflow:
+
+```bash
+  bundle exec ruby starter.rb query completed-id
+```
+
+As expected, this will output "Query result for id complete-id: post-patch".
+
+Following these stages, we have successfully altered our workflow code.
+
diff --git a/patching/my_activities.rb b/patching/my_activities.rb
new file mode 100644
index 0000000..3a3fe65
--- /dev/null
+++ b/patching/my_activities.rb
@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'temporalio/activity'
+
+module Patching
+  module MyActivities
+    class PrePatch < Temporalio::Activity::Definition
+      def execute
+        'pre-patch'
+      end
+    end
+
+    class PostPatch < Temporalio::Activity::Definition
+      def execute
+        'post-patch'
+      end
+    end
+  end
+end
diff --git a/patching/starter.rb b/patching/starter.rb
new file mode 100644
index 0000000..f85e140
--- /dev/null
+++ b/patching/starter.rb
@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'temporalio/client'
+
+# Create a client
+client = Temporalio::Client.connect('localhost:7233', 'default')
+
+command, workflow_id = ARGV
+raise('Missing command argument. Valid commands are start and query') if command.nil?
+raise('Missing workflow_id') if workflow_id.nil?
+
+case command
+when 'start'
+  client.start_workflow(
+    'MyWorkflow',
+    id: workflow_id,
+    task_queue: 'patching-sample'
+  )
+  puts "Started workflow with id #{workflow_id}"
+when 'query'
+  handle = client.workflow_handle(workflow_id)
+  result = handle.query(:result)
+  puts "Query result for id #{workflow_id}: #{result}"
+else
+  raise('Invalid command. Valid commands are start and query')
+end
diff --git a/patching/worker.rb b/patching/worker.rb
new file mode 100644
index 0000000..eb31082
--- /dev/null
+++ b/patching/worker.rb
@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'my_activities'
+require_relative 'workflow_1_initial'
+require_relative 'workflow_2_patched'
+require_relative 'workflow_3_deprecated'
+require_relative 'workflow_4_complete'
+require 'logger'
+require 'temporalio/client'
+require 'temporalio/worker'
+
+# Create a Temporal client
+client = Temporalio::Client.connect(
+  'localhost:7233',
+  'default',
+  logger: Logger.new($stdout, level: Logger::INFO)
+)
+
+workflow_versions = {
+  'initial' => Patching::MyWorkflow1Initial,
+  'patched' => Patching::MyWorkflow2Patched,
+  'deprecated' => Patching::MyWorkflow3Deprecated,
+  'complete' => Patching::MyWorkflow4Complete
+}
+
+workflow_version = ARGV.first || raise('Missing argument for workflow version')
+workflow = workflow_versions[workflow_version] ||
+           raise("Unrecognized workflow #{workflow_version}. Accepted values are #{workflow_versions.keys.join(', ')}")
+# Create worker with the activities and workflow
+worker = Temporalio::Worker.new(
+  client:,
+  task_queue: 'patching-sample',
+  activities: [Patching::MyActivities::PrePatch, Patching::MyActivities::PostPatch],
+  workflows: [
+    workflow
+  ]
+)
+
+# Run the worker until SIGINT
+puts 'Starting worker (ctrl+c to exit)'
+worker.run(shutdown_signals: ['SIGINT'])
diff --git a/patching/workflow_1_initial.rb b/patching/workflow_1_initial.rb
new file mode 100644
index 0000000..49adc10
--- /dev/null
+++ b/patching/workflow_1_initial.rb
@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'my_activities'
+
+module Patching
+  class MyWorkflow1Initial < Temporalio::Workflow::Definition
+    workflow_name 'MyWorkflow'
+    workflow_query_attr_reader :result
+
+    def execute
+      @result = Temporalio::Workflow.execute_activity(
+        MyActivities::PrePatch,
+        start_to_close_timeout: 5 * 60
+      )
+    end
+  end
+end
diff --git a/patching/workflow_2_patched.rb b/patching/workflow_2_patched.rb
new file mode 100644
index 0000000..5ebe3a3
--- /dev/null
+++ b/patching/workflow_2_patched.rb
@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'my_activities'
+
+module Patching
+  class MyWorkflow2Patched < Temporalio::Workflow::Definition
+    workflow_name 'MyWorkflow'
+    workflow_query_attr_reader :result
+
+    def execute
+      @result = if Temporalio::Workflow.patched :my_patch
+                  Temporalio::Workflow.execute_activity(
+                    MyActivities::PostPatch,
+                    start_to_close_timeout: 5 * 60
+                  )
+                else
+                  Temporalio::Workflow.execute_activity(
+                    MyActivities::PrePatch,
+                    start_to_close_timeout: 5 * 60
+                  )
+                end
+    end
+  end
+end
diff --git a/patching/workflow_3_deprecated.rb b/patching/workflow_3_deprecated.rb
new file mode 100644
index 0000000..69dd8ba
--- /dev/null
+++ b/patching/workflow_3_deprecated.rb
@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'my_activities'
+
+module Patching
+  class MyWorkflow3Deprecated < Temporalio::Workflow::Definition
+    workflow_name 'MyWorkflow'
+    workflow_query_attr_reader :result
+
+    def execute
+      Temporalio::Workflow.deprecate_patch :my_patch
+      @result = Temporalio::Workflow.execute_activity(
+        MyActivities::PostPatch,
+        start_to_close_timeout: 5 * 60
+      )
+    end
+  end
+end
diff --git a/patching/workflow_4_complete.rb b/patching/workflow_4_complete.rb
new file mode 100644
index 0000000..f8bb76f
--- /dev/null
+++ b/patching/workflow_4_complete.rb
@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'temporalio/workflow'
+require_relative 'my_activities'
+
+module Patching
+  class MyWorkflow4Complete < Temporalio::Workflow::Definition
+    workflow_name 'MyWorkflow'
+    workflow_query_attr_reader :result
+
+    def execute
+      @result = Temporalio::Workflow.execute_activity(
+        MyActivities::PostPatch,
+        start_to_close_timeout: 5 * 60
+      )
+    end
+  end
+end

From 211ed87a817d0aead28cd0f2cf83bafc2797b72b Mon Sep 17 00:00:00 2001
From: Chris Olszewski <chris.olszewski@temporal.io>
Date: Thu, 9 Oct 2025 14:51:57 -0400
Subject: [PATCH 2/3] add comments

---
 patching/starter.rb            | 2 ++
 patching/worker.rb             | 1 +
 patching/workflow_2_patched.rb | 1 +
 3 files changed, 4 insertions(+)

diff --git a/patching/starter.rb b/patching/starter.rb
index f85e140..c0b4243 100644
--- a/patching/starter.rb
+++ b/patching/starter.rb
@@ -11,6 +11,7 @@
 
 case command
 when 'start'
+  # Start a workflow with the given id
   client.start_workflow(
     'MyWorkflow',
     id: workflow_id,
@@ -18,6 +19,7 @@
   )
   puts "Started workflow with id #{workflow_id}"
 when 'query'
+  # Obtain a workflow handle for the given id and query the result
   handle = client.workflow_handle(workflow_id)
   result = handle.query(:result)
   puts "Query result for id #{workflow_id}: #{result}"
diff --git a/patching/worker.rb b/patching/worker.rb
index eb31082..74474ae 100644
--- a/patching/worker.rb
+++ b/patching/worker.rb
@@ -23,6 +23,7 @@
   'complete' => Patching::MyWorkflow4Complete
 }
 
+# Select which version of the workflow the worker should use
 workflow_version = ARGV.first || raise('Missing argument for workflow version')
 workflow = workflow_versions[workflow_version] ||
            raise("Unrecognized workflow #{workflow_version}. Accepted values are #{workflow_versions.keys.join(', ')}")
diff --git a/patching/workflow_2_patched.rb b/patching/workflow_2_patched.rb
index 5ebe3a3..204e694 100644
--- a/patching/workflow_2_patched.rb
+++ b/patching/workflow_2_patched.rb
@@ -9,6 +9,7 @@ class MyWorkflow2Patched < Temporalio::Workflow::Definition
     workflow_query_attr_reader :result
 
     def execute
+      # Decide which activity to use based on workflow's patch status
       @result = if Temporalio::Workflow.patched :my_patch
                   Temporalio::Workflow.execute_activity(
                     MyActivities::PostPatch,

From e4cd38836fd14c7f1a9328c843c9792be9f0a52b Mon Sep 17 00:00:00 2001
From: Chris Olszewski <chris.olszewski@temporal.io>
Date: Fri, 10 Oct 2025 10:31:37 -0400
Subject: [PATCH 3/3] pr feedback

---
 patching/README.md                |  3 +-
 patching/starter.rb               |  2 +-
 patching/workflow_1_initial.rb    |  2 +-
 patching/workflow_2_patched.rb    |  4 +-
 patching/workflow_3_deprecated.rb |  4 +-
 patching/workflow_4_complete.rb   |  2 +-
 test/patching/my_workflow_test.rb | 68 +++++++++++++++++++++++++++++++
 7 files changed, 76 insertions(+), 9 deletions(-)
 create mode 100644 test/patching/my_workflow_test.rb

diff --git a/patching/README.md b/patching/README.md
index e49e92e..dd35a80 100644
--- a/patching/README.md
+++ b/patching/README.md
@@ -109,7 +109,7 @@ As expected, this will output "Query result for id deprecated-id: post-patch".
 ## Stage 4
 
 Once we know we don't even have any workflows running on "Stage 2" or before (i.e. the workflow with the patch with both code paths), we can just remove the patch deprecation altogether.
-To use the patch complete workflow, stop the workflow from before and start it again with:
+To use the patch complete workflow, stop the worker from before and start it again with:
 
 ```bash
   bundle exec ruby worker.rb complete
@@ -139,4 +139,3 @@ And if we execute a query against the latest workflow:
 As expected, this will output "Query result for id complete-id: post-patch".
 
 Following these stages, we have successfully altered our workflow code.
-
diff --git a/patching/starter.rb b/patching/starter.rb
index c0b4243..2e5d6ad 100644
--- a/patching/starter.rb
+++ b/patching/starter.rb
@@ -13,7 +13,7 @@
 when 'start'
   # Start a workflow with the given id
   client.start_workflow(
-    'MyWorkflow',
+    :MyWorkflow,
     id: workflow_id,
     task_queue: 'patching-sample'
   )
diff --git a/patching/workflow_1_initial.rb b/patching/workflow_1_initial.rb
index 49adc10..da48813 100644
--- a/patching/workflow_1_initial.rb
+++ b/patching/workflow_1_initial.rb
@@ -5,7 +5,7 @@
 
 module Patching
   class MyWorkflow1Initial < Temporalio::Workflow::Definition
-    workflow_name 'MyWorkflow'
+    workflow_name :MyWorkflow
     workflow_query_attr_reader :result
 
     def execute
diff --git a/patching/workflow_2_patched.rb b/patching/workflow_2_patched.rb
index 204e694..3c3345d 100644
--- a/patching/workflow_2_patched.rb
+++ b/patching/workflow_2_patched.rb
@@ -5,12 +5,12 @@
 
 module Patching
   class MyWorkflow2Patched < Temporalio::Workflow::Definition
-    workflow_name 'MyWorkflow'
+    workflow_name :MyWorkflow
     workflow_query_attr_reader :result
 
     def execute
       # Decide which activity to use based on workflow's patch status
-      @result = if Temporalio::Workflow.patched :my_patch
+      @result = if Temporalio::Workflow.patched(:my_patch)
                   Temporalio::Workflow.execute_activity(
                     MyActivities::PostPatch,
                     start_to_close_timeout: 5 * 60
diff --git a/patching/workflow_3_deprecated.rb b/patching/workflow_3_deprecated.rb
index 69dd8ba..3e100e9 100644
--- a/patching/workflow_3_deprecated.rb
+++ b/patching/workflow_3_deprecated.rb
@@ -5,11 +5,11 @@
 
 module Patching
   class MyWorkflow3Deprecated < Temporalio::Workflow::Definition
-    workflow_name 'MyWorkflow'
+    workflow_name :MyWorkflow
     workflow_query_attr_reader :result
 
     def execute
-      Temporalio::Workflow.deprecate_patch :my_patch
+      Temporalio::Workflow.deprecate_patch(:my_patch)
       @result = Temporalio::Workflow.execute_activity(
         MyActivities::PostPatch,
         start_to_close_timeout: 5 * 60
diff --git a/patching/workflow_4_complete.rb b/patching/workflow_4_complete.rb
index f8bb76f..8d2314b 100644
--- a/patching/workflow_4_complete.rb
+++ b/patching/workflow_4_complete.rb
@@ -5,7 +5,7 @@
 
 module Patching
   class MyWorkflow4Complete < Temporalio::Workflow::Definition
-    workflow_name 'MyWorkflow'
+    workflow_name :MyWorkflow
     workflow_query_attr_reader :result
 
     def execute
diff --git a/test/patching/my_workflow_test.rb b/test/patching/my_workflow_test.rb
new file mode 100644
index 0000000..836300e
--- /dev/null
+++ b/test/patching/my_workflow_test.rb
@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'test'
+require 'patching/my_activities'
+require 'patching/workflow_1_initial'
+require 'patching/workflow_2_patched'
+require 'patching/workflow_3_deprecated'
+require 'patching/workflow_4_complete'
+
+require 'securerandom'
+require 'temporalio/client'
+require 'temporalio/testing'
+require 'temporalio/worker'
+
+module Patching
+  class PatchingWorkflowTest < Test
+    def setup
+      @task_queue = "tq-#{SecureRandom.uuid}"
+    end
+
+    def with_handle(env, workflow, id)
+      Temporalio::Worker.new(
+        client: env.client,
+        activities: [MyActivities::PrePatch, MyActivities::PostPatch],
+        task_queue: @task_queue,
+        workflows: [workflow]
+      ).run do
+        handle = env.client.start_workflow(
+          :MyWorkflow, id:, task_queue: @task_queue
+        )
+        yield handle
+      end
+    end
+
+    def test_workflow
+      Temporalio::Testing::WorkflowEnvironment.start_local do |env|
+        initial_handle = with_handle(env, MyWorkflow1Initial, 'initial-id') do |handle|
+          handle.result
+          assert_equal 'pre-patch', handle.query(:result)
+          handle
+        end
+
+        patched_handle = with_handle(env, MyWorkflow2Patched, 'patched-id') do |handle|
+          handle.result
+          assert_equal 'pre-patch', initial_handle.query(:result)
+          assert_equal 'post-patch', handle.query(:result)
+          handle
+        end
+
+        deprecated_handle = with_handle(env, MyWorkflow3Deprecated, 'deprecated-id') do |handle|
+          handle.result
+          assert_raises(Temporalio::Error::WorkflowQueryFailedError) { initial_handle.query(:result) }
+          assert_equal 'post-patch', patched_handle.query(:result)
+          assert_equal 'post-patch', handle.query(:result)
+          handle
+        end
+
+        with_handle(env, MyWorkflow4Complete, 'deprecated-id') do |complete_handle|
+          complete_handle.result
+          assert_raises(Temporalio::Error::WorkflowQueryFailedError) { initial_handle.query(:result) }
+          assert_raises(Temporalio::Error::WorkflowQueryFailedError) { patched_handle.query(:result) }
+          assert_equal 'post-patch', deprecated_handle.query(:result)
+          assert_equal 'post-patch', complete_handle.query(:result)
+        end
+      end
+    end
+  end
+end