Skip to main content

Backward Compatibility Policy

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.

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.
  • Action: Users will never be required to manually clear, migrate, or restructure the data directory during a standard upgrade.

Non-Guaranteed 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 "Non-Guaranteed" to "Stable" as the platform matures. We view our users as partners in this evolution and value your feedback in shaping a more resilient ecosystem.