Versioning and stability

Semantic versioning

SDK versions are major.minor.patch. A patch release fixes behavior without changing the surface. A minor release adds surface: new methods, new optional parameters, new event kinds your existing handlers can ignore. A major release is the only place a breaking change can happen, and majors are rare by design.

What holds still within a major

Within a major version: no shipped method is renamed or removed, no parameter changes meaning, no event or type loses a field, and no error code changes identity. Additions are the only kind of change. This is a design rule on our side, not an aspiration: a change that would break the shipped surface is treated as a defect in the change, not a cost of progress.

Anything documented in the reference is covered. Surface that exists in the SDK but throws not_yet_implemented is explicitly not covered: it is reserved vocabulary, and its final shape may differ.

Deprecations

When something is scheduled to change in the next major, its deprecation is announced in the per-SDK changelog at least one minor release before the major that removes it, with the replacement named. Nothing disappears without a version you can hold while you migrate.

Wire compatibility

The SDK talks to a service we operate, so compatibility runs in both directions. Every server release is tested against the published SDK artifacts, as installed from the public registries, before it reaches production. A server change that would break an SDK version customers are running fails that gate and does not ship. You do not need to upgrade the SDK in lockstep with our server releases.