Safe Deploys #3598
Safe Deploys #3598
Conversation
Co-authored-by: angelazhou32 <141692465+angelazhou32@users.noreply.github.com>
| - A **Worker Deployment** is a deployment or service across multiple versions. In a rainbow deploy, a deployment can have multiple active deployment versions running at once. | ||
| - A **Worker Deployment Version** is a version of a deployment or service. It can have multiple Workers, but they all run the same build. | ||
| - A **Build ID**, in combination with a Worker Deployment name, identifies a single Worker Deployment Version. | ||
| - You can declare each Workflow type to have a **Versioning Behavior**, either `pinned` or `auto-upgrade`. |
There was a problem hiding this comment.
nit: I believe we avoid code-quotes in language-agnostic sections, instead preferring just capitalized Pinned/Auto-Upgrade
|
|
||
| Most users who are migrating to rainbow deploys from rolling deploys will start by defaulting to `auto-upgrade` until they have had time to annotate their Workflows. | ||
| This default is the most similar to the legacy behavior. | ||
| Auto-upgrade workflows won't be restricted to a single version and and need to be kept replay-safe manually, e.g. with [replay testing](https://docs.temporal.io/workflow-execution#replay). |
There was a problem hiding this comment.
- nit: Remove "and and"
- I don't think this is the right link target, it has nothing to do with testing. And doesn't talk about patching. I think learning about patching is primary and replay testing secondary.
|
|
||
| See [Legacy Worker Versioning](worker-versioning-legacy) if you still need those docs. | ||
| ## Runtime checking {#runtime-checking} |
There was a problem hiding this comment.
This section I think would be better as a link out to what I'm adding here: #3614 (would be nice to get it merged)
Which has a more complete list, along with more context and allows us to avoid repeating it per-language
There was a problem hiding this comment.
Nice, and thanks for the bump. Approved (with one optional comment) on my end.
Maybe we decouple these PRs, though and take this comment for the next one?
| #### Behavior When Not Replaying | ||
|
|
||
| If the execution is not replaying, when it encounters a call to `patched()`, it first checks the event history. |
There was a problem hiding this comment.
There's some useful content in here that maybe could go into a shared section for all core-based languages. It's not something people would commonly need to refer to, so I can certainly see removing it from here - but it can be useful for debugging and more complete understanding.
…monize with per-lang docs
… language in Worker Versioning Section
| - [Versioning with patching](#workflow-patching): make sure your code changes are compatible across versions of your Workflow. | ||
| - [Worker Versioning](#worker-versioning): keep Workers tied to specific code revisions, so that old Workers can run old code paths and new Workers can run new code paths. (Note: If you were using this method experimentally prior to 2025, refer to the [Worker Versioning Legacy](/encyclopedia/worker-versioning-legacy) docs, but note that these are planned for deprecation.) | ||
|
|
||
| You can use one strategy, or a combination. |
There was a problem hiding this comment.
I suggest "either strategy" in place of "one strategy."
|
|
||
| #### Worker Versioning {#worker-versioning} | ||
|
|
||
| To learn more about Worker Versioning, go [here](/production-deployment/worker-deployments/worker-versioning). |
There was a problem hiding this comment.
Suggest:
For a deeper discussion of Worker Versioning, see our [Worker Versioning] page (/product-deployment/worker-deployments/worker-versioning).
We avoid having links be the single word "here," as it's bad accessibility practice.
|
|
||
| The Temporal Platform requires that Workflow code (Workflow Definitions) be deterministic in nature. | ||
| This requirement means that developers should consider how they plan to handle changes to Workflow code over time. | ||
|
|
||
| A versioning strategy is even more important if your Workflow Executions live long enough that a Worker must be able to execute multiple versions of the same Workflow Type. Temporal Platform provides Workflow Versioning APIs. | ||
| A versioning strategy is even more important if your Workflow Executions live long enough to run on multiple versions of your Worker. Temporal Platform provides Workflow Versioning APIs. |
There was a problem hiding this comment.
I think there's something I don't understand behind this change. "run on multiple versions of your Worker" doesn't seem equivalent to "a Worker must be able to execute" the Workflow Execution. Is the Workflow doing the action, or is the action occurring on the Worker?
| ## Worker Versioning | ||
| ### Testing a Workflow for replay safety. | ||
|
|
||
| To make sure your Workflow doesn't need a patch, or that you've patched it successfully, you should incorporate [Replay Testing](/develop/dotnet/testing-suite#replay). |
There was a problem hiding this comment.
"To make sure your Workflow doesn't need a patch" sounds like the default assumption is that it wouldn't. Does it make sense to say "To determine whether your Workflow needs a patch, or that..." ?
There was a problem hiding this comment.
I would suggest this is an example of why further qualifying replay testing beyond a general recommendation does not add clarity.
this won't build yet because it's missing the new safe deploys page, but this way you can see how I'm changing our existing SDK versioning pages before adding that content (all 6 plus the new section should be ready by Wednesday).