Versioning inheritance semantics #3716
Conversation
|
Am leaning to thinking that this is the point at which we add an Encyclopedia page for this stuff, so that way we can include explanations as well. Want me to re-tool this PR a bit along those lines? |
yes that would be amazing! lmk what you need from me. definitely feel free to check out this branch and do whatever you want to it! For what it's worth, I think it would be nice to have Auto-Upgrade and Pinned definitions in the encyclopedia so that those can be linked to in places where those terms are used. Right now they're only defined in the "getting started with worker versioning" section. Also, the "version statuses" (Inactive -> Active -> Draining -> Drained) are good candidates for encyclopedia IMO |
|
Okey doke. @carlydf thoughts? Just a starting point but I think we can continue to push stuff here as needed. |
|
|
||
| - [Versioning Behaviors](#versioning-behaviors) | ||
| - [Versioning Statuses](#versioning-statuses) | ||
| - [Inheritance Semantics](#inheritance-semantics) |
There was a problem hiding this comment.
Not sure what this means at this stage, so it should be contextualized. Inheritance of what? At this point I'm thining of OOP.
There was a problem hiding this comment.
Changed to "Continue-as-new, Child Workflow, and Retry Semantics" as below.
| 1. **Inactive**: The version exists because a Worker with that version has polled the server. If this version never becomes Active, it will never be Draining or Drained. | ||
| 2. **Active**: The version is either Current or Ramping, so it is accepting new Workflows and existing auto-upgrade Workflows. | ||
| 3. **Draining**: The version stopped being Current or Ramping, and it has open pinned Workflows running on it. It is possible to be Draining and have no open pinned Workflows for a short time, since the drainage status is updated periodically. | ||
| 4. **Drained**: The version was draining and now all the pinned Workflows that were running on it are closed. |
There was a problem hiding this comment.
mention queries?
There was a problem hiding this comment.
Added:
Closed Workflows may still re-run some code paths if they are Queried within their Retention Period and Workers with that version are still polling.
| A Worker Deployment Version moves through the following states: | ||
|
|
||
| 1. **Inactive**: The version exists because a Worker with that version has polled the server. If this version never becomes Active, it will never be Draining or Drained. | ||
| 2. **Active**: The version is either Current or Ramping, so it is accepting new Workflows and existing auto-upgrade Workflows. |
There was a problem hiding this comment.
Should we mention the CLI command that triggers this? Or link out to the appropriate section?
There was a problem hiding this comment.
Leaning toward no here — I don't think it follows directly in the Encyclopedia.
|
|
||
| 1. **Inactive**: The version exists because a Worker with that version has polled the server. If this version never becomes Active, it will never be Draining or Drained. | ||
| 2. **Active**: The version is either Current or Ramping, so it is accepting new Workflows and existing auto-upgrade Workflows. | ||
| 3. **Draining**: The version stopped being Current or Ramping, and it has open pinned Workflows running on it. It is possible to be Draining and have no open pinned Workflows for a short time, since the drainage status is updated periodically. |
There was a problem hiding this comment.
Let's give a hint as to why this would happen to help people get a feel for what might have caused it. If I'm like "why is my deployment draining?" this could answer that question. Something like "the version stopped being Current or Ramping, either because A or B."
There was a problem hiding this comment.
How's:
- Draining: The version has open pinned Workflows running on it, but stopped being Current or Ramping, usually because a newer version has been deployed. It is possible to be Draining and have no open pinned Workflows for a short time, since the drainage status is updated only periodically.
|
|
||
| ### Inheritance Semantics {#inheritance-semantics} | ||
|
|
||
| When Workflows start new runs, versioning behavior and version information may be inherited depending on the scenario. This section explains how inheritance works across different Workflow execution patterns. |
There was a problem hiding this comment.
nit: was briefly confused. inherited by what?
Active voice might help here
"When Workflows start new runs, the new run may inherit their versioning behavior."
There was a problem hiding this comment.
Continue-as-new, Retry, and Child Workflow Semantics
|
|
||
| #### Inheritance Rules Overview | ||
|
|
||
| **Key Principle**: Auto-upgrade Workflows never inherit versions, while Pinned workflows may inherit under specific conditions. |
There was a problem hiding this comment.
"Pinned workflows may inherit under specific conditions"
I'd like to give a more accessible summary here for the folks who don't want to read the whole thing.
And my hope is we can generalizee
There was a problem hiding this comment.
@carlydf? I'm admittedly having a hard time figuring out how to summarize this into a consistent rule that doesn't rely on reading through the various conditions.
|
|
||
| ##### Child Workflows | ||
|
|
||
| **When Parent is Pinned:** |
There was a problem hiding this comment.
I think this section can be way shorter.
Since, for example, for a child workflow, the default task queue is the parent's, we can start people off with the default.
"By default, PINNED workflows will pass their version to any PINNED children. If you set the task queue on such a child workflow to one in a Different deployment, it will be pinned to that Deployment's current version."
I also wonder if this can be generalized (i.e. task queue semantics are the same for continue as new)
| - Child's first Workflow task executes in the same version as its parent | ||
| - If child is also Pinned: child remains Pinned to the inherited version for its lifetime | ||
| - If child is Auto-Upgrade: child's behavior changes to Auto-Upgrade after the first task completes | ||
| - If child's Task Queue is not in the same Worker Deployment as parent: no inheritance occurs, child starts on Current Version of its task queue |
There was a problem hiding this comment.
Do we have a succinct way of describing the "version that the workflow will go to--current if current and with some probability N if it's ramping at N"?
There was a problem hiding this comment.
Ramping and Current versions are both the "Active" versions of the Deployment, so we could start using that. I agree it would be good to have a succinct way of saying that fact
What does this PR do?
Document versioning inheritance semantics
Notes to reviewers
I'm not sure where to put this section, and am very open to feedback saying this is confusing.
We have reasons for all of these decisions, I just didn't include the reasons because it's already a bit wordy and I didn't want to summarize an entire design doc worth of scenarios.