Versioning Training: Versioning Workflows with the Patching API

Training
1

Hello!

I could be wrong on this, but either this section of the training is confusing me or it is not correct.

The section of the Temporal Versioning training called “Versioning Workflows with the Patching API” has a subsection “Step 2: Deprecate Patch” that is not very clear to me.

One the description of this subsection it clearly states that you shouldn’t be removing calls to the patched() function on your Workflow code when deploying the deprecated_patch() call. However, in the example code that follows the explanation, the calls to patched() are removed along with the old code, and you only see the deprecated_patch() call.

Could someone help me understand this bit of the training for me?

Thank you!

2

Hi Adrian,

Thanks for pointing this out to us! I agree that part of our course was a little more “clear as mud” than crystal clear – and I’ve just made a revision to how it appears in the LMS. Here’s the relevant change:

### Step 2: Deprecate Patch

When you have introduced a patch into your Workflow using the `patched()` function
and it has been successfully deployed, you can begin to deprecate the patch. This is where the
[`deprecate_patch()`](https://python.temporal.io/temporalio.workflow.html#deprecate_patch)
function comes in. The `deprecate_patch()` function is used to mark a particular
patch (identified by an `id`) as deprecated, meaning that the Workflow
should no longer rely on the patch, and you can now retire this code.

Once you're confident that your Workflows are no longer running the pre-patch
code paths, you can deploy your code with `deprecate_patch()`. These Workers
will be running the most up-to-date version of the Workflow code, which no
longer requires the patch. The `deprecate_patch()` function works similarly to
the `patched()` function by recording a marker in the Workflow history. This
marker does not fail replay when Workflow code does not emit it.

This code is safe to deploy once all "v3" or earlier Workflows are complete:

@workflow.defn
class ShippingConfirmation:
    @workflow.run
    async def run(self) -> None:
        workflow.deprecate_patch("changed_notification_type")
        self._result = await workflow.execute_activity(
            send_email,
            schedule_to_close_timeout=timedelta(minutes=5),
        )

Deprecated patches serve as a bridge between the pre-patch code paths and the
post-patch code paths, and are useful for avoiding errors resulting from patched
code paths in your Workflow Execution History.

### Step 3: Safely Deploy New Code

You can safely remove support for older versions once you are certain that there
are no longer any open Workflow Executions based on that version. You can use
the following List Filter syntax for this:

Essentially, deprecate_patch() is only meant to be used after old executions using the pre-patch code paths have all resolved, to continue providing compatibility for Replay and Queries without causing Execution History errors. Thanks for pointing this out to us!