docs/development/testing/ctf/fidl_api_compatibility_testing.md

# FIDL API compatibility testing

Note: Compatibility testing documents are being overhauled in Q2
2024.  Some information in this document is out of date. See
https://fxbug.dev/339893257 for details.

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][SDK Categories] 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:

1. An in-development API level - This is what Fuchsia developers make additive changes to.
2. 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](/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.

1. Annotate new, not-yet-stable APIs with `@available(added=HEAD)`.
1. Annotate newly stable APIs that are ready to go to partners and will not change
   with `@available(added=NEXT)`.
1. 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].

[FIDL versioning]: /docs/reference/fidl/language/versioning.md
[Fuchsia API levels]: /docs/contribute/governance/rfcs/0002_platform_versioning.md
[SDK Categories]: /docs/contribute/governance/rfcs/0165_sdk_categories.md
[FIDL compatibility guide]: /docs/development/languages/fidl/guides/compatibility/README.md
[API evolution guide]: /docs/development/api/evolution.md