Version the workflow contract
Record which definition version started each execution and preserve compatibility for its stored state. Avoid changing the meaning of an existing field or step identifier if active runs may still read it.
For a breaking change, deploy a new version and route new work to it while allowing older runs to complete. If migration is necessary, define and validate a conversion for each persisted state before applying it.
Plan rollout and recovery
Estimate how many executions remain active and how long they may run. Monitor failures by version and keep the previous definition available until old executions finish or are safely migrated.
Test representative in-progress states against the new code, including retries and wait steps. Document how to pause, resume, or roll back runs so operators do not have to guess during a release.