Skip to main content

Making revisions to Workflow code

Making revisions to existing Workflow code can be challenging. Your Workflow code must be deterministic. This means your changes to that code have to be as well. Changes to your Workflow code that qualify as non-deterministic need to be protected by using the Versioning APIs within your Workflow code.

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. However, if you are using encrypted Payloads, which is a typical and recommended setup in production, you may not be able to decrypt the fetched histories. Additionally, 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.