docs/concepts/versioning/README.md

# Platform versioning

This document provides a high-level overview of platform versioning in Fuchsia,
focusing on the key concepts that platform developers need to understand.

## API Levels

The core of Fuchsia's versioning system lies in **API levels**. These levels
represent snapshots of the Fuchsia API surface at a specific point in time. The
API surface encompasses various elements, including FIDL interfaces, system
calls, and libraries. When using the SDK to develop a component for Fuchsia, you
specify a target API level. This target API level signifies the specific version
of the Fuchsia API surface that your component requires and ensures
compatibility with devices supporting that level. Just like other platforms,
Fuchsia regularly publishesnew API levels.

Fuchsia devices support a specific set of API levels. If a device supports a
particular API level, it guarantees that all functionalities associated with
that level are available and functional. Conversely, if a device doesn't support
the target API level of a component, the component won't run on that device.
Fuchsia can also drop support for older API levels, a process referred to as
**retiring**. This mechanism allows the platform to evolve while maintaining
backward compatibility.

For more information on how API levels and a Fuchsia release work, see
[API levels][api-levels] and [Release][fuchsia-release], respectively.

### Special API levels

While the primary focus is on stable, numbered API levels, Fuchsia also
incorporates special API levels for development purposes. These special API
levels, `NEXT` and `HEAD`, allow platform developers to introduce and test new
features and API changes before they are integrated into a stable release.
However, targeting special API levels imposes additional constraints, and they
are not intended for general component development.

For more information on special API levels, see
[Special API levels][special-api-levels].

## Key considerations for platform developers

As a platform developer, understanding how API levels impact development is
crucial. When making changes to the API surface, these modifications should be
made at `HEAD` while you are developing. Once the changes are ready to be
published, you should change `HEAD` to `NEXT`. Since the `NEXT` API level,
represents the next version to be published, any change will be incorporated
into the next published API level. For example, if the current published API level
is 25, any changes made in `NEXT` will be applied to API level 26.

Platform components must maintain support for all API levels currently supported
by Fuchsia. Fuchsia supports all API levels with a phase of Supported and
Sunset. This requirement ensures backward compatibility. The
[`sdk/version_history.json`] file lists the phase of each API level. Even
if a method is removed in a newer API level, platform components must continue
to implement it if older, still-supported API levels include that method.
Bindings and tools often assist in this process, ensuring necessary interfaces
remain available for older API level targets.

For more information about the phases of an API level, see
[Phases][api-levels-phases].

Even with the help these tools provide, maintaining compatibility is difficult,
and platform developers must think carefully about it. When in doubt, remember
this: a component built against a given API level should behave the same way on
any Fuchsia device that supports that API level.

For more information on compatibility, see [Compatibility][compatibility-doc].

[compatibility-doc]: /docs/concepts/versioning/compatibility.md
[fuchsia-release]: /docs/concepts/versioning/release.md
[special-api-levels]: /docs/concepts/versioning/api_levels.md#special-api-levels
[api-levels]: /docs/concepts/versioning/api_levels.md
[api-levels-phases]: /docs/concepts/versioning/api_levels.md#phases
[`sdk/version_history.json`]: /sdk/version_history.json