Create API compatibility and Supported Versions Policy for Feast

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 #676
  • Adding Field Status metadata to Online Serving PR #658
  • Generalising Source model from being tied to Kafka PR #685
  • Evolving Feast’s 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.)

[woop]

Thanks for taking the time to write this out @mrzzy. A pleasant surprise.

Developers having to maintain too many API versions.

You touched on a core issue here. If we had unlimited manpower and bandwidth we could easily maintain multiple code paths and gradually deprecate old APIs. We don’t, unfortunately.

I like the idea behind the policy you are proposing. I think we should start with a pebble (to steal @ches’s saying). We can keep the policy as simple as possible for the time being, and over time it can grow to contain more and more information.

We are already documenting breaking api changes with the compat/breaking label. This means that all PRs should have a release note that describes this change. We could then compile these release notes (perhaps even automatically) into a release notes document.

Here is an example of what I mean: https://cloud.google.com/kubernetes-engine/docs/release-notes

This would allow users to at least identify upcoming breakages and plan for their upgrade.

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.)

It would be great if you could provide “reasonable defaults” here that we can attack as a straw man. We probably want to only have breaking changes on minor version bumps (patch versions are for… patches). And minimally we want to have 1 minor version of backward compatibility, but I can see ourselves breaking that rule as we are with projects right now.

How do we provide a clear way for developers to announce breaking changes to users? (ie Slack? Deprecation notices? Issues? etc.)

Perhaps every release should come out with an email on the mailing list. This should also communicate breaking changes and possibly a link to find out more information on upgrades.

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.)

I had something like this in mind: https://docs.getdbt.com/docs/guides/migration-guide/upgrading-from-0-10-to-0-11

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.