The definition code of a Temporal Workflow must be deterministic because Temporal uses event sourcing to reconstruct the Workflow state by replaying the saved history event data on the Workflow definition code. This means that any incompatible update to the Workflow Definition code could cause a non-deterministic issue if not handled correctly.
Introduction to Versioning
Because we design for potentially long running Workflows at scale, versioning with Temporal works differently. We explain more in this optional 30 minute introduction: https://www.youtube.com/watch?v=kkP899WxgzY
How to use Worker Versioning in Python
To use Worker Versioning in Python, you need to do the following:
- Determine and assign a Build ID to your built Worker code, and opt in to versioning.
- Tell the Task Queue your Worker is listening on that Build ID, and whether it's compatible with an existing Build ID.
Assign a Build ID to your Worker
Let's say you've chosen
deadbeef as your Build ID, which might be a short git commit hash (a reasonable choice as Build ID).
To assign it in your Worker code, assign at least the following Worker Options:
worker = Worker(
# ... register workflows & activities, etc
That's all you need to do in your Worker code. Importantly, if you start this Worker, it won't receive any tasks yet. That's because you need to tell the Task Queue about your Worker's Build ID first.
Tell the Task Queue about your Worker's Build ID
Now you can use the SDK (or the Temporal CLI) to tell the Task Queue about your Worker's Build ID. You might want to do this as part of your CI deployment process.
This code adds the
deadbeef Build ID to the Task Queue as the sole version in a new version set, which becomes the default for the queue.
New Workflows execute on Workers with this Build ID, and existing ones will continue to process by appropriately compatible Workers.
If, instead, you want to add the Build ID to an existing compatible set, you can do this:
"your_task_queue_name", BuildIdOpAddNewCompatible("deadbeef", "some-existing-build-id")
This code adds
deadbeef to the existing compatible set containing
some-existing-build-id and marks it as the new default Build ID for that set.
You can also promote an existing Build ID in a set to be the default for that set:
You can also promote an entire set to become the default set for the queue. New Workflows will start using that set's default build.
Specify versions for Commands
By default, Activities, Child Workflows, and Continue-as-New use the same compatible version set as the Workflow that invoked them if they're also using the same Task Queue.
If you want to override this behavior, you can specify your intent via the
argument available on the methods you use to invoke these Commands.
For more information refer to the conceptual documentation.
For example, if you want to use the latest default version for an Activity, you can call it like so: