Skip to main content

Backward Compatibility

The following text defines the compatibility guarantees for our software across version updates. Our primary goal is to provide a seamless upgrade experience while maintaining the flexibility to evolve the platform.

Our Commitment​

Although we do not provide formal guarantees for all areas, our engineering philosophy is to avoid breaking changes whenever possible. In cases where a breaking change is necessary, we aim to provide:

  • Clear documentation of the change in the release notes.
  • Guidance on adapting configurations for the new version.

Scope: Per Major Release​

For Stable releases, backward compatibility is scoped to a major release. Within a single major release, Stable releases are backward compatible: upgrading between Stable versions that share the same major version (for example, 10.4.0 to 10.5.0) will not introduce breaking changes.

  • Within a major release: Stable releases are backward compatible. The Non-Guaranteed Stable Area will not break between Stable versions that share the same major version.
  • Across major releases: Breaking changes are reserved for major releases. A new major release (for example, 10.x to 11.0.0) is how we signal that a breaking change to the Non-Guaranteed Stable Area may be required. Any such change is documented in the release notes with guidance for migrating.

Guaranteed Stable Area​

The Application Data Directory is the only current area with a strict backward-compatibility guarantee. We provide automatic migrations to ensure old data remains compatible with newer versions.

While we strive for 100% reliability, edge cases may occur. If you encounter a migration failure, please report the issue, and we will prioritize a patch to address it.

  • Guarantee: Data stored within this directory will remain compatible with all future software versions, including across major releases.
  • Action: Users will never be required to manually clear, migrate, or restructure the data directory during a standard upgrade, even when upgrading to a new major version.

Non-Guaranteed Stable Area​

To allow for rapid innovation and architectural improvements, the following areas do not carry a backward-compatibility guarantee. Breaking changes may occur in:

  • Pipelines: Including all individual pipeline components and configurations.
  • Metrics: Including structural changes to names, paths, and types.
  • Networking & Blueprints: Configurations and default blueprints.
  • APIs: All gRPC API definitions and endpoints.
  • Hub: The Control Plane wireformat.

Our Path to Stability​

We understand that breaking changes can be disruptive. To minimize impact and build a predictable environment for our users, we follow these internal guidelines:

  • Deprecation Warnings: Whenever possible, we will mark features as "Deprecated" at least one minor version before removal, giving you time to plan your transition.
  • Automated Testing: Every release undergoes rigorous regression testing to ensure that our data guarantees remain unbreakable.
  • Open Communication: If a change impacts your specific workflow, our engineering team is available to discuss technical workarounds and migration strategies.

Our goal is to eventually move more areas from the Non-Guaranteed Stable Area to the Guaranteed Stable Area as the platform matures. We view our users as partners in this evolution and value your feedback in shaping a more resilient ecosystem.