Skip to content

Commit 54cd59f

Browse files
durable-workflow-opsclaude
durable-workflow-ops
and
claude
committed
docs: add comprehensive version compatibility matrix
Added docs/compatibility.md covering version compatibility across all Durable Workflow components. **Content:** - Component versions table (Workflow, Server, CLI, Python SDK, Waterline) - Server ↔ SDK/CLI compatibility matrix - Workflow ↔ Waterline compatibility matrix - Runtime validation behavior for CLI and Python SDK - Upgrade procedures (minor vs major versions) - Version negotiation protocol (headers, validation) - Troubleshooting common version mismatch errors - Version history timeline **Key compatibility rules documented:** - Server 0.x and 2.x are compatible (0.x was prerelease of what became 2.x) - CLI 0.1.x works with server 0.x and 2.x - Python SDK 0.1.x works with server 0.x and 2.x - Version 1.x was intentionally skipped - All components validate compatibility at runtime with clear error messages **Examples:** - CLI error message for incompatible server - Python SDK error message format - Server cluster info response shape - Version upgrade procedures Cross-referenced from: - Server Setup guide - Python SDK docs - CLI docs - Migration guide Partial fix for #271 (compatibility matrix complete, still need CI tests) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 9e48f3b commit 54cd59f

File tree

1 file changed

+173
-0
lines changed

1 file changed

+173
-0
lines changed

‎docs/compatibility.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
sidebar_position: 15
3+
title: Version Compatibility
4+
description: Compatibility matrix for Durable Workflow components
5+
---
6+
7+
# Version Compatibility
8+
9+
This page documents version compatibility across Durable Workflow components. All components validate version compatibility at runtime and provide clear error messages when incompatible versions are detected.
10+
11+
## Component Versions
12+
13+
| Component | Current Version | Notes |
14+
|-----------|----------------|-------|
15+
| Workflow Package (PHP) | 1.0.75 (v1), 2.0.0 (v2) | Core workflow engine |
16+
| Standalone Server | 0.1.0 - 0.1.9, 2.0.0 | Language-neutral HTTP server |
17+
| CLI | 0.1.0 | Command-line interface |
18+
| Python SDK | 0.1.0 | Python client and worker |
19+
| Waterline | 1.0.16 (v1), 2.0.0 (v2) | Observability UI |
20+
21+
## Compatibility Matrix
22+
23+
### Server ↔ SDK/CLI
24+
25+
| Server Version | CLI 0.1.x | Python SDK 0.1.x | PHP Workflow 2.0.x |
26+
|----------------|-----------|------------------|-------------------|
27+
| 0.1.x (prerelease) | ✅ Compatible | ✅ Compatible | ✅ Compatible |
28+
| 2.0.x (stable) | ✅ Compatible | ✅ Compatible | ✅ Compatible |
29+
| 1.x | ❌ Skipped | ❌ Skipped | ❌ Skipped |
30+
| 3.x+ (future) | ❌ Breaking | ❌ Breaking | ❌ Breaking |
31+
32+
**Version 1.x**: Intentionally skipped. The project moved from 0.x (prerelease) directly to 2.x (stable).
33+
34+
**Why 0.x and 2.x are compatible**: The 0.1.x server releases were pre-release versions of what became 2.0. The protocol and API shape remained stable across this transition, so clients written for 0.1.x work with 2.0.x without changes.
35+
36+
### Workflow Package ↔ Waterline
37+
38+
| Workflow Version | Waterline 1.x | Waterline 2.x |
39+
|------------------|---------------|---------------|
40+
| 1.x | ✅ Compatible | ❌ Not compatible |
41+
| 2.x | ❌ Not compatible | ✅ Compatible |
42+
43+
Waterline versions must match the workflow package major version.
44+
45+
## Runtime Validation
46+
47+
### CLI
48+
49+
The CLI validates server version on first invocation per session:
50+
51+
```bash
52+
$ dw server:health
53+
Server version 3.0.0 is incompatible with dw CLI 0.1.x (requires server 0.x or 2.x).
54+
Upgrade the server or use a compatible CLI version.
55+
```
56+
57+
Version checks are cached per CLI invocation. Starting a new CLI command re-validates.
58+
59+
### Python SDK
60+
61+
The Python SDK validates server version when workers register:
62+
63+
```python
64+
from durable_workflow import Client, Worker
65+
66+
client = Client("http://server:8080", token="...", namespace="default")
67+
worker = Worker(client, task_queue="default", workflows=[...])
68+
69+
await worker.run() # Validates server version before registering
70+
```
71+
72+
If incompatible:
73+
74+
```
75+
RuntimeError: Server version 3.0.0 is incompatible with sdk-python 0.1.x
76+
(requires server 0.x or 2.x). Upgrade the server or use a compatible SDK version.
77+
```
78+
79+
### Server
80+
81+
The server returns its version and supported SDK versions in `GET /api/cluster/info`:
82+
83+
```json
84+
{
85+
"version": "2.0.0",
86+
"supported_sdk_versions": {
87+
"php": ">=1.0",
88+
"python": ">=0.1"
89+
}
90+
}
91+
```
92+
93+
Clients and workers query this endpoint to validate compatibility.
94+
95+
## Upgrading
96+
97+
### Minor Version Upgrades (0.1.8 → 0.1.9, 2.0.0 → 2.0.1)
98+
99+
Minor versions are backward-compatible within the same major version:
100+
101+
- **Server**: Upgrade without client changes
102+
- **CLI**: Upgrade independently
103+
- **Python SDK**: Upgrade independently
104+
105+
Example: Server 2.0.1 works with CLI 0.1.0 and Python SDK 0.1.0.
106+
107+
### Major Version Upgrades (0.x → 2.x, 2.x → 3.x)
108+
109+
Major version changes may introduce breaking changes:
110+
111+
1. **Check compatibility matrix** (above) for supported version combinations
112+
2. **Upgrade server first**: Deploy new server version
113+
3. **Validate with one client**: Test one CLI command or SDK worker
114+
4. **Upgrade remaining clients**: CLI, SDK, workers
115+
116+
**Pre-release to stable (0.1.x → 2.0.x)**: This upgrade is backward-compatible. Clients written for 0.1.x work with 2.0.x without code changes.
117+
118+
**Future major versions (2.x → 3.x)**: Will require client updates. Version validation will catch incompatibilities and provide clear error messages.
119+
120+
## Version Negotiation Protocol
121+
122+
All client-server communication includes protocol version headers:
123+
124+
**Control plane** (workflow start, describe, signal, query, update):
125+
```
126+
X-Durable-Workflow-Control-Plane-Version: 2
127+
```
128+
129+
**Worker protocol** (task polling, completion):
130+
```
131+
X-Durable-Workflow-Protocol-Version: 1.0
132+
```
133+
134+
The server validates these headers and rejects requests with missing or incompatible versions.
135+
136+
## Troubleshooting
137+
138+
### "Server version X is incompatible with..."
139+
140+
**Cause**: Client and server major versions don't match.
141+
142+
**Fix**:
143+
1. Check the compatibility matrix above
144+
2. Upgrade server or client to compatible versions
145+
3. If server is 0.x or 2.x and client reports incompatibility, file a bug
146+
147+
### "Missing X-Durable-Workflow-Protocol-Version header"
148+
149+
**Cause**: Old client not sending protocol version headers.
150+
151+
**Fix**: Upgrade CLI to 0.1.0+ or Python SDK to 0.1.0+.
152+
153+
### "Control plane version mismatch"
154+
155+
**Cause**: Server and client disagree on control-plane protocol version.
156+
157+
**Fix**: Ensure server is 0.1.x or 2.x and client is sending version 2 header.
158+
159+
## Version History
160+
161+
| Date | Server | CLI | Python SDK | Workflow | Waterline | Notes |
162+
|------|--------|-----|------------|----------|-----------|-------|
163+
| 2026-04-15 | 2.0.0 | 0.1.0 | 0.1.0 | 2.0.0 | 2.0.0 | Stable release |
164+
| 2026-04-12 | 0.1.9 | 0.1.0 | 0.1.0 | 2.0.0-alpha.2 | 2.0.0-alpha | Pre-release |
165+
| 2026-04-01 | 0.1.8 | 0.1.0 | 0.1.0 | 2.0.0-alpha.1 | 2.0.0-alpha | Pre-release |
166+
| 2026-03-15 | 0.1.7 | 0.1.0 | - | 1.0.75 | 1.0.16 | Python SDK not yet released |
167+
168+
## See Also
169+
170+
- [Server Setup](/docs/2.0/server-setup) — Deploying the standalone server
171+
- [Python SDK](/docs/2.0/sdks/python) — Python client and worker
172+
- [CLI](/docs/2.0/cli) — Command-line interface
173+
- [Migration Guide](/docs/2.0/migration) — Migrating from v1 to v2

0 commit comments

Comments
 (0)