We use API compatibility tests to ensure that SDK Users targeting supported platform API levels aren't broken by changes to FIDL APIs at tip of tree. All FIDL APIs published in the partner Fuchsia SDKs should be automatically tested for backward API compatibility. This document describes what API compatibility tests are and how to use them.
Concepts
FIDL versioning
The reader should be familiar with FIDL versioning.
API levels
To understand API compatibility tests, it's important to have a basic understanding of Fuchsia API levels. An API level denotes the set of APIs available when building an application. They are unsigned 64-bit integers which are assigned to the Fuchsia platform in increasing order.
There are two API levels that are useful to keep in mind:
- An in-development API level - This is what Fuchsia developers make additive changes to.
- A stable API level - This level is stable and its surface area will not change.
The current implementation of platform versioning does not yet reflect this: In the Fuchsia source tree, we record API and ABI version history, as well as level status ("in-development" and "supported" aka stable) at //sdk/version_history.json.
API level evolution
An API level goes through several phases, illustrated by the following diagram:
+----------------+ freeze +--------+ drop +-------------+
START -> | in-development | -----> | stable | -----> | unsupported |
+----------------+ +--------+ +-------------+
In-development
In this phase the API level is in active evolution, as new API elements may be introduced, deprecations may be introduced, etc. Breaking changes to APIs introduced at this level are not allowed and contributors should make sure there are no partners still relying on APIs removed at this level.
Stable
The API level can no longer receive changes. Contributors should start introducing APIs to partners at the next in-development API level. When we "freeze" an API level, the level may no longer receive changes. This usually happens immediately before a branch cut. It will remain supported for at least 6 weeks or until the Fuchsia platform drops support for it. APIs can be deprecated at this level but not deleted.
Unsupported
When we drop support for a level, Fuchsia contributors are free to delete or modify any APIs at this level, and we stop running compatibility tests for this level. There's no longer any guarantee that end users can successfully target this API level.
Resolving compatibility issues
Usually compatibility issues can be fixed by adding @available annotations on FIDL
declarations.
Below are some good guidelines to follow when changing FIDL APIs.
- Annotate new, not-yet-stable APIs with
@available(added=HEAD). - Annotate newly stable APIs that are ready to go to partners and will not change
with
@available(added=NEXT). - When removing an API, first make sure no partners are still using the API, then
annotate the old API with
@available(..., removed=NEXT).
For more examples, see the API evolution guide and the FIDL compatibility guide.