Compatibility policy
The engine and the SDK evolve over time, but existing integrations shouldn't break on every update. This page explains how the engine, the SDK, the Control API, and the client libraries are versioned, and how to tell which pieces work together.
ViveEngine versioning
The engine uses Semantic Versioning with three components: major.minor.patch.
| Component | Meaning |
|---|---|
| Major | A new generation that introduces breaking changes. |
| Minor | New features, while existing integrations keep working. |
| Patch | Bug fixes that do not affect compatibility. |
The engine is distributed separately, as an installer — not through the SDK. See Install the engine.
SDK versioning
The SDK isn't a single package. It's several components, each versioned and released on its own:
- API specifications — the interface definition files, such as the
.protofor the Control API and the header for the plugin API. All specs share the same version. - Client libraries — per-language wrappers, such as C# and Go. Each language library uses its own version.
Every component uses Semantic Versioning, and the first two components — major and minor — are tied to the engine version.
When a new engine minor version ships — say 1.3.0 — the SDK components are bumped to 1.3.0 too. After that, each component can make independent bug-fix releases that bump only its patch version, separately from the engine and from each other.
Component compatibility
An SDK component is compatible with the engine when the first two components of its version are greater than or equal to the engine's:
SDK component 1.3.x -> engine 1.3.x or newer
For example, a component at 1.3.x is compatible with engine 1.3.x, and with 1.4.x and newer within the same major version. A version of 1.3 means the component targets the engine 1.3 API, so it requires at least engine 1.3 and is forward-compatible for the rest of the major version.
The patch component is independent and doesn't affect engine compatibility. For example, C# library 1.3.2 works with engine 1.3.0, even though the engine's patch version is lower.
Component tags
Because the components are versioned separately, their Git tags are separate too. Instead of one v1.2.3 tag for the whole SDK, each component uses its own tag prefix. Pick the tag that matches the component in use.
| Component | Tag format |
|---|---|
| API specifications | api/v1.2.3 |
| .NET components | net/v1.2.3 |
| Go components | go/v1.2.3 |
gRPC API updates
The Control API belongs to the API specifications SDK component.
Its major version is additionally part of the gRPC package name. This allows multiple major versions co-exist to keep old clients working.
The minor version changes when non-breaking features are added, including API changes. Clients generated from an older spec keep working. Clients generated from a newer spec gain access to the new features but also require engine that's at least as new as the hew spec.
The patch version changes for bug fixes only and don't affect compatibility.
Incompatible changes
If a change ever has to break compatibility, the major version increases — e.g. v2 package appears. Even then, the old major version stays available in parallel with the new one, so existing clients keep working during migration.
How compatibility is maintained
Within a major version, the Control API stays compatible by following the Protocol Buffers rules for evolving a schema safely — adding fields instead of renumbering or reusing them, never changing field types, and so on.
See the Protocol Buffers guide on updating a message type for the full list of rules. We follow those recommendations for every API update.
Client library updates
Client libraries for different languages are managed as separate SDK components.
Similarly to gRPC API updates, major version updates are breaking, minor versions updates are backward-compatible, and patch versions don't affect compatibility. Updating to a newer library gains access to new features and raises the minimum required engine.
Incompatible changes
Unlike the gRPC API, multiple major versions of a library don't coexist in one project. Older releases stay available through their component tags, so existing projects can keep using them.
Crossing a major (breaking) version is handled by the language's package manager. Usually it won't upgrade across a major on its own — you have to switch to the new major explicitly.
How compatibility is maintained
Within a major version, each library preserves backward compatibility following its language's conventions. What counts as a breaking change depends on the language:
| Language | Compatibility level | Reference |
|---|---|---|
| C# | Binary | Breaking changes and .NET libraries |
| Go | Source-level | Keeping your modules compatible |