WIP: Replay #6

mnichols · 2024-10-24T15:44:24Z

Versioning and Replay are effectively, coupled.
This PR adds a Versions doc to get down in the weeds of deciding on the right Version strategy.

Replay test guidance is still under construction in the doc.

tomwheeler

I made some suggestions, mostly style issue such as punctuation or capitalization. I spotted and commented on a few technical issues, though they were fairly minor.

This is fantastic. You covered the right things. Your explanations were clear and easy to follow.

tomwheeler · 2024-10-31T22:30:19Z

docs/curriculum/Tests.md

@@ -91,68 +90,6 @@ that is, the only reason an "Activity" component even exists is because the orch
 _Does your Workflow definition have conditional branches?_ 


Suggested change

_Does your Workflow definition have conditional branches?_

_Does your Workflow Definition have conditional branches?_

This is capitalized, as per the Temporal Style Guide

tomwheeler · 2024-10-31T22:30:41Z

docs/curriculum/Tests.md

@@ -91,68 +90,6 @@ that is, the only reason an "Activity" component even exists is because the orch
 _Does your Workflow definition have conditional branches?_ 
 If so, mocking or stubbing the Activity definitions themselves can reduce test complexity by directly providing their results, allowing you to verify the branch paths.


Suggested change

If so, mocking or stubbing the Activity definitions themselves can reduce test complexity by directly providing their results, allowing you to verify the branch paths.

If so, mocking or stubbing the Activity Definitions themselves can reduce test complexity by directly providing their results, allowing you to verify the branch paths.

Capitalized, as per the Temporal Style Guide

Will fix these over in the docs repo since these are moved over there now Thanks!

tomwheeler · 2024-10-31T22:38:39Z

docs/curriculum/Versions.md

-* Compare the implications of choosing _In Situ_ Versioning to _Routed_ Versioning
-* Address message versioning as it applies to _In Situ_ Versioning
+* Address message versioning strategies 
+* Compare the implications of choosing _Patched_ Workflow Versioning to _Routed_ Workflow Versioning


Just a comment, but the term "Routed Workflow Versioning" isn't one that's used in our documentation (neither the API docs from Engineering nor the docs produced by the Education team). I saw later in the document where you clarify that this is a category of versioning strategies, not a specific implementation, which relieves my concern that someone wouldn't find any results for a search on this term.

tomwheeler · 2024-10-31T22:39:09Z

docs/curriculum/Versions.md

+
+## Message Versioning
+
+Temporal saves in its event history the serialized representation of your messages used for inputs and outputs of all interactions with a Workflow.


Suggested change

Temporal saves in its event history the serialized representation of your messages used for inputs and outputs of all interactions with a Workflow.

Temporal saves in its Event History the serialized representation of your messages used for inputs and outputs of all interactions with a Workflow.

tomwheeler · 2024-10-31T22:40:42Z

docs/curriculum/Versions.md

+your Applications. 
+
+You can avoid this by:
+* Implement an explicit message version strategy that keeps messages backwards compatible.


Suggested change

* Implement an explicit message version strategy that keeps messages backwards compatible.

* Implementing an explicit message version strategy that keeps messages backwards compatible.

This change in verb tense enables this text to complete the sentence leading into it ("You can avoid this by ...")

tomwheeler · 2024-11-01T01:22:06Z

docs/curriculum/Versions.md

+**External Workflow History Storage**
+
+* _Cons_
+    * This can be problematic in ephemeral containers used for CICD purposes.


Suggested change

* This can be problematic in ephemeral containers used for CICD purposes.

* This can be problematic in ephemeral containers used for CI/CD purposes.

tomwheeler · 2024-11-01T01:22:23Z

docs/curriculum/Versions.md

+    * This can be problematic in ephemeral containers used for CICD purposes.
+    * This might require non-trivial authnz to an external file storage solution.
+    * Garbage collection on histories might be needed to keep storage costs down
+        * Detecting which histories are eligible for collection can be complex for Workflow Definitions that are long-running and do not implement Continue As New


Suggested change

* Detecting which histories are eligible for collection can be complex for Workflow Definitions that are long-running and do not implement Continue As New

* Detecting which histories are eligible for collection can be complex for Workflow Definitions that are long-running and do not implement Continue-As-New

tomwheeler · 2024-11-01T01:26:24Z

docs/curriculum/Versions.md

+        * Detecting which histories are eligible for collection can be complex for Workflow Definitions that are long-running and do not implement Continue As New
+    * The `DataConverter` used to generate the histories _must_ be used when doing these tests. 
+* _Pros_
+    * No need to maintain more than one implementation in VCS for the same Workflow Type in the same source version.


Suggested change

* No need to maintain more than one implementation in VCS for the same Workflow Type in the same source version.

* No need to maintain more than one implementation in a version control system (VCS) for the same Workflow Type in the same source version.

I suspect that some developers might not be familiar with the abbreviation, so I recommend spelling it out on first reference here. In my experience, some (older) people say "revision control system." I suspect that some younger people have only ever known git and therefore have no need to generalize about what kind of tool it is.

tomwheeler · 2024-11-01T01:27:06Z

docs/curriculum/Versions.md

+
+> The Patched Versioning strategy is convenient because `Starters` don't need to update their code with version changes or coordinate deployments with services hosting Temporal Workers.
+>
+> Note that in all SDKs except Java need to specify a `string` WorkflowType name explicitly in the Worker registration,type decorator or attribute options


Suggested change

> Note that in all SDKs except Java need to specify a `string` WorkflowType name explicitly in the Worker registration,type decorator or attribute options

> Note that in all SDKs except Java need to specify a `string` Workflow Type name explicitly in the Worker registration,type decorator or attribute options

tomwheeler · 2024-11-01T01:34:38Z

docs/curriculum/Writes.md

+_Signal Handler_
+
+1. Inside the Signal handler: Set (propose) the received input message onto common (shared) Workflow Execution state
+2. Inside the Workflow main method: Apply the side effect(s) caused by the proposal (input).


Is the word "main" in "Workflow main method" necessary here?

I fear that someone might confuse this with the main method in a Java class (i.e., the entry point). Since only one method for a given Workflow Type will be designated as @WorkflowMethod, I think "Workflow method" is sufficient to describe it.

mnichols added 11 commits October 3, 2024 14:11

reorganizing replay and versions

aeed94c

tweak init of state in curriculum

49ed2d0

some clarity on message handling

12ee329

more compression of decisioning with versioning

5a5cb19

clean up loop docs

07684be

push

1ebea69

some clean up of patched versioning

2c9dfa2

comparisons of Routed Versioning strategy

1a522d9

smaller recommendation

2cc84ad

add deployment notes on patched version

b59d86a

noted on removing old versions

342d543

tomwheeler reviewed Nov 1, 2024

View reviewed changes

mnichols added 3 commits April 20, 2025 15:59

replay docs

1927d37

QOL

9b4c987

move docs to temporal-jumpstart repo

76d63e1

mnichols merged commit ad1b774 into main Apr 21, 2025
2 checks passed

		@@ -91,68 +90,6 @@ that is, the only reason an "Activity" component even exists is because the orch
		_Does your Workflow definition have conditional branches?_

		@@ -91,68 +90,6 @@ that is, the only reason an "Activity" component even exists is because the orch
		_Does your Workflow definition have conditional branches?_
		If so, mocking or stubbing the Activity definitions themselves can reduce test complexity by directly providing their results, allowing you to verify the branch paths.


		## Message Versioning

		Temporal saves in its event history the serialized representation of your messages used for inputs and outputs of all interactions with a Workflow.

	* Implement an explicit message version strategy that keeps messages backwards compatible.
	* Implementing an explicit message version strategy that keeps messages backwards compatible.

	* This can be problematic in ephemeral containers used for CICD purposes.
	* This can be problematic in ephemeral containers used for CI/CD purposes.

	* Detecting which histories are eligible for collection can be complex for Workflow Definitions that are long-running and do not implement Continue As New
	* Detecting which histories are eligible for collection can be complex for Workflow Definitions that are long-running and do not implement Continue-As-New

	* No need to maintain more than one implementation in VCS for the same Workflow Type in the same source version.
	* No need to maintain more than one implementation in a version control system (VCS) for the same Workflow Type in the same source version.

	> Note that in all SDKs except Java need to specify a `string` WorkflowType name explicitly in the Worker registration,type decorator or attribute options
	> Note that in all SDKs except Java need to specify a `string` Workflow Type name explicitly in the Worker registration,type decorator or attribute options

WIP: Replay #6

WIP: Replay #6

Uh oh!

Conversation

mnichols commented Oct 24, 2024

Uh oh!

tomwheeler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants