Background

As Feast evolves and matures over time, and new users integrate Feast into their systems, we are faced with two conflicting needs:

• Developers need a way make breaking changes to add new features/rectify design decisions that no longer make sense:
  • Removing versions in FeatureSets PR Add support for feature set updates and remove versions #676
  • Adding Field Status metadata to Online Serving PR Add Field Status metadata to Online Serving #658
  • Generalising Source model from being tied to Kafka PR Refactor Source & Job data model and Stop Duplicate Ingestion Jobs #685
  • Evolving Feast's Data model Feast API: Feature references, concept hierarchy, and data model #479
• Users need time to transition their systems that are built on top of Feast during which Feast should offer compatibility guarantees . Upgrades should be as painless as possible. They also need to aware about what changes they have to make to transition from one version to another.
  • Introduce changes in Evolutionally Friendly way by @ches
  • Versioning APIs by @zhilingc

For guidance on how to resolve this we can look at Kubernetes does it:

• Handling Version Skew in Components/Backward Compatiblity
• What constitutes a compatible change
• Versioning APIs to introducing backward incompatible changes
• Deprecating APIs

User Facing APIs in Question for context:

• Ingestion (FeatureRow) API
• Core API
• Serving API
• Feast Python SDK/CLI
• Feast Java SDK
• Feast Golang SDK

Problem

How do we resolve the two conflicting needs of Developers and Users while satisfy the following requirements:

• Providing a clear way for Developers to introduce breaking changes as Feast evolves.
• Creating a clear transition path for users integrate these changes into their systems.
• Prevent code bloat resulting in Developers having to maintain too many API versions.
• Introduce backward compatibility to buy users time to transition their systems to the new API.

Proposed Solution

Create and API compatibility and Support Versions Policy to document how:

• What steps should developers take introduce breaking changes to the API? (ie Bump API Version, Deprecation etc.)
• What & How much API compatibility guarantees can we provide to users? (ie Deprecation happens 1 minor version before removal, Backwards compatibility with older SDKs up to 1 minor release. etc.)
• How do we provide a clear way for developers to announce breaking changes to users? (ie Slack? Deprecation notices? Issues? etc.)
• How can we provide a clear transition path for existing users to upgrade to new versions with potentially breaking changes? (ie Highlight with action required in Release note what needs to be changed etc.)