documentation
documentation copied to clipboard
temporalio
[Feature Request] Document SDK versioning scheme
As discussed on slack with @mfateev and @Spikhalskiy we'd like to apply a semver incompatible versioning scheme for SDKs. Temporal SDKs can break compatibility in either public APIs or history incompatibility. We'd like to reserve major version changes to history incompatible changes, that is, if you deploy this new version your running workflows could stop running and you'll run into determinism errors. We'll use the minor for API breaking changes and patch for new features and bugfixes.
“We’ll use the minor for API breaking changes and patch for new features and bugfixes.” I don’t think we agreed on this part.
We use minor for new features, bugfixes and minor incompatible API changes that lead to compilation errors. Patch versions are for patches/hotfixes.
So, the only difference with semver that we allow minor versions to carry SOME (relatively minor and trivial) API incompatibilities, like change of parameter types or removing a method that clearly was added by mistake or bad design. Which should be done with consideration and only if we are really fixing some problem or mistake by this change. Or if the change is happening in a new unstable evolving functionality.
Big API changes when we revisit and break a good chunk of our most used methods should go into a major release.
Big API changes when we revisit and break a good chunk of our most used methods should go into a major release.
👍
We use minor for new features, bugfixes and minor incompatible API changes that lead to compilation errors.
👍
Patch versions are for patches/hotfixes, why not for features too? Then we can use minor to denote that it's a breaking change.
@bergundy is there a concrete ask of the docs team on this yet? Have you all decided on what the version schema is for each SDK?
We'll come up with an accurate description of the schema and update. We haven't really gotten back to this discussion since October.
We could probably link more to these Github changelogs, I think they're the source of truth on this right now: https://github.com/temporalio/sdk-go/releases
These are linked from https://docs.temporal.io/dev-guide/java/introduction#updates, but hard to find.
We've had some internal discussions solidifying our scheme but have not had the time to come up with a document yet.