Update sample code and instructions

Author: AnatoliB

samples-v2/orchestration_versioning/README.md

@@ -1,3 +1,44 @@
 # Versioning
 
 This directory contains a Function app that demonstrates how to make changes to an orchestrator function without breaking existing orchestration instances.
+
+The orchestrator function has two code paths:
+
+1. The old path invoking `activity_a`.
+2. The new path invoking `activity_b` instead.
+
+While `defaultVersion` in `host.json` is set to `1.0`, the orchestrator will always follow the first path, producing the following output:
+
+```
+Orchestration version: 1.0
+Suborchestration version: 1.0
+Hello from A!
+```
+
+When `defaultVersion` in `host.json` is updated (for example, to `2.0`), *new orchestration instances* will follow the new path, producing the following output:
+
+```
+Orchestration version: 2.0
+Suborchestration version: 2.0
+Hello from B!
+```
+
+What happens to existing orchestration instances that were started before the `defaultVersion` change? Waiting for an external event in the middle of the orchestrator provides a convenient opportunity to emulate a deployment while orchestration instances are still running:
+
+1. Create a new orchestration by invoking the HTTP trigger (`http_start`).
+2. Wait for the orchestration to reach the point where it is waiting for an external event.
+3. Stop the app.
+4. Change `defaultVersion` in `host.json` to `2.0`.
+5. Deploy and start the updated app.
+6. Trigger the external event.
+7. Observe that the orchestration output.
+
+```
+Orchestration version: 1.0
+Suborchestration version: 2.0
+Hello from A!
+```
+
+Note that the value returned by `context.version` is permanently associated with the orchestrator instance and is not impacted by the `defaultVersion` change. As a result, the orchestrator follows the old execution path to guarantee deterministic replay behavior.
+
+However, the suborchestration version is `2.0` because it was invoked this suborchestration was created *after* the `defaultVersion` change.

samples-v2/orchestration_versioning/function_app.py

@@ -15,30 +15,32 @@ async def http_start(req: func.HttpRequest, client):
 
 @myApp.orchestration_trigger(context_name="context")
 def my_orchestrator(context: df.DurableOrchestrationContext):
+    # context.version contains the value of defaultVersion in host.json
+    # at the moment when the orchestration was created.
     if (context.version == "1.0"):
         # Legacy code path
-        activity_result = yield context.call_activity('say_hello', "v1.0")
+        activity_result = yield context.call_activity('activity_a')
     else:
         # New code path
-        activity_result = yield context.call_activity('say_hello', f"v{context.version}")
+        activity_result = yield context.call_activity('activity_b')
 
-    # While the orchestration is waiting for the external event,
-    # stop the app, update the defaultVersion in host.json to "2.0",
-    # then restart the app and send a "Continue" event.
-    # This orchestration instance should continue with the old version.
+    # Provide an opportunity to update and restart the app
     context.set_custom_status("Waiting for Continue event...")
     yield context.wait_for_external_event("Continue")
     context.set_custom_status("Continue event received")
 
-    # New orchestration instances (including sub-orchestrations)
-    # will use the current defaultVersion specified in host.json.
+    # New sub-orchestrations will use the current defaultVersion specified in host.json
     sub_result = yield context.call_sub_orchestrator('my_sub_orchestrator')
     return [f'Orchestration version: {context.version}', f'Suborchestration version: {sub_result}', activity_result]
 
 @myApp.orchestration_trigger(context_name="context")
 def my_sub_orchestrator(context: df.DurableOrchestrationContext):
     return context.version
 
-@myApp.activity_trigger(input_name="city")
-def say_hello(city: str) -> str:
-    return f"Hello {city}!"
+@myApp.activity_trigger()
+def activity_a() -> str:
+    return f"Hello from A!"
+
+@myApp.activity_trigger()
+def activity_b() -> str:
+    return f"Hello from B!"