feat: implement workflow versioning support

[timl3136]

What changed?
Added support for workflow versioning

Why?
Important feature now that we have marker state machine

How did you test it?
unit tests

Potential risks

Release notes

Documentation Changes

[codecov]

Codecov Report

❌ Patch coverage is 95.53571% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...internal/workflow/statemachine/decision_manager.py	92.68%	1 Missing and 2 partials ⚠️
cadence/_internal/workflow/versioning.py	93.10%	1 Missing and 1 partial ⚠️

Files with missing lines	Coverage Δ
cadence/_internal/workflow/context.py	94.25% <100.00%> (+0.50%)	⬆️
...rnal/workflow/statemachine/marker_state_machine.py	97.26% <100.00%> (+0.76%)	⬆️
cadence/_internal/workflow/workflow_engine.py	92.46% <ø> (+1.86%)	⬆️
cadence/testing/_workflow_environment.py	86.46% <100.00%> (+0.24%)	⬆️
cadence/workflow.py	95.21% <100.00%> (+0.06%)	⬆️
cadence/_internal/workflow/versioning.py	93.10% <93.10%> (ø)
...internal/workflow/statemachine/decision_manager.py	94.54% <92.68%> (+1.18%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gitar-bot]

CI failed: 1 code formatting failure in the integration tests from unformatted Python files; all other steps and checks passed successfully.

Overview

A single tooling and formatting check failure occurred during CI due to an unformatted test file in the new workflow versioning integration tests across 2 job logs.

Failures

Code Formatting Check Failed (confidence: high)

• Type: tooling
• Affected jobs: 92465604432, 93584672192
• Related to change: yes
• Root cause: The newly added integration test file tests/integration_tests/workflow/test_versioning.py does not adhere to the project's formatting rules, causing the formatter to fail with exit code 1.
• Suggested fix: Run the project's formatting tool locally (e.g., using uv run python scripts/... or ruff format), commit the formatting changes, and push the updated branch.

Summary

• Change-related failures: 1 code formatting check failure in tests/integration_tests/workflow/test_versioning.py
• Infrastructure/flaky failures: 0
• Recommended action: Format the codebase using the project's configured formatter/linter command, then commit and push the formatting fixes.

Code Review ✅ Approved 3 resolved / 3 findings

Implements workflow versioning support with get_version validation and selection options, addressing duplicated version logic, marker recording issues, and strict type checking. All identified issues have been successfully resolved.

✅ 3 resolved

✅ Quality: Version selection/validation logic duplicated across two contexts

📄 cadence/testing/_workflow_environment.py:290-304 📄 cadence/_internal/workflow/context.py:348-362
_InMemoryWorkflowContext.get_version (testing/_workflow_environment.py) re-implements the change_id validation, option-precedence selection, and range-validation logic that Context.get_version factors into _validate_version_arguments, _select_version, and _validate_selected_version. The two copies already differ (inline vs. helpers, dict[str,int] vs dict[str,int|None]), so they can silently drift as the versioning rules evolve, causing the in-memory test harness to accept/reject inputs differently from production. Consider extracting the shared selection/validation helpers into a module-level function reused by both.

✅ Quality: Strict marker detail check skipped for DefaultDataConverter subclasses

📄 cadence/_internal/workflow/context.py:484-497
_decode_recorded_version gates the strict JSON well-formedness check with type(self.data_converter()) is DefaultDataConverter, so any subclass of DefaultDataConverter bypasses _validate_default_version_details even though it still uses the default JSON encoding. If this exact-type check is intentional (only the canonical default converter is validated) a brief comment would prevent future confusion; otherwise consider isinstance to cover subclasses.

✅ Bug: get_version never records a marker; min_supported > -1 always fails

📄 cadence/_internal/workflow/context.py:349-361 📄 cadence/_internal/workflow/statemachine/decision_manager.py:288-302 📄 cadence/_internal/workflow/statemachine/marker_state_machine.py:171-174 📄 cadence/testing/_workflow_environment.py:290-303
version_marker_result builds a MarkerStateMachine via .completed(...), whose get_decision() returns None whenever state is COMPLETED, so a Version marker decision is never emitted (confirmed by the integration test now asserting version_markers == []). During live (non-replay) execution get_version therefore always resolves to DEFAULT_VERSION (-1) and never advances to a new version. Worse, the standard multi-revision versioning pattern that passes min_supported > DEFAULT_VERSION (e.g. get_version(id, 1, 2)) will hit validate_resolved_version(-1, 1, 2) and raise FatalDecisionError, failing the decision task/workflow — the tests were changed to use DEFAULT_VERSION as min_supported specifically to avoid this. If recording is intentionally deferred, get_version should reject min_supported > DEFAULT_VERSION with a clear, documented error (or the recording path should be implemented) rather than silently always returning -1 and crashing on the common case.

Tip

Comment Gitar fix CI or enable auto-apply: gitar auto-apply:on

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}