Skip to main content

Making revisions to Workflow code

Temporal Workflows must be deterministic in terms of the events that they generate server-side. Changes to your Workflows that would create different server-side events, or events in a different order, need to be protected by using the Versioning APIs within your Workflow code. You can also use Worker Versioning to pin your deployments to specific code revisions. Activities do not need to be deterministic.

Use Replay Testing before and during your deployments​

The best way to verify that your code won't cause non-determinism errors once deployed is to use replay testing.

Replay testing takes one or more existing Workflow Histories that ran against a previous version of Workflow code and runs them against your current Workflow code, verifying that your new code is compatible with the provided history.

There are multiple points in your development lifecycle where running replay tests can make sense. They exist on a spectrum, with shortest time to feedback on one end, and most representative of a production deployment on the other.

  • During development, replay testing lets you get feedback as early as possible on whether your changes are compatible.
  • During pre-deployment validation (such as during some automated deployment validation) you can get feedback in a more representative environment. For example, you might fetch histories from a live Temporal environment (whether production or some kind of pre-production) and use them in replay tests.
  • At deployment time, your environment is production, but you are using the new code to replay recent real-world Workflow histories.

When you're writing changes to Workflow code, you can fetch some representative histories from your pre-production or production Temporal environment and verify they work with your changes. You can do the same with the pre-merge CI pipeline. If your Workflows contain any personally identifiable information, you should be using a Failure Converter to ensure that data is encoded.

Implement a deployment-time replay test​

The key to a successful safe deployment is to break it into two phases: a verification phase, where you'll run the replay test, followed by the actual deployment of your new Worker code. Refer to the replay testing docs of each SDK for implementation details.