# Fuchsia SDK Contributor Guide

This section includes documentation for contributing to the [Fuchsia API
Surface](https://fuchsia.dev/docs/glossary/README#fuchsia-api-surface) and the [IDK](https://fuchsia.dev/docs/development/idk).

*Technically*, it may be more appropriate to call this the "IDK Contributor
Guide", as the APIs and libraries that make up the API Surface are first added
to the IDK, which is then turned into an SDK distribution. However,
colloquially and in code, we almost exclusively say "the SDK". Regardless, if
you're looking to "change the SDK" in some way, you're probably in the right
place.

## Contributing to an API in the SDK

To contribute to the [Fuchsia API Surface](https://fuchsia.dev/docs/glossary/README#fuchsia-api-surface), do the
following:

- Evaluate whether your change is large or small.

  - If you have a small, incremental change to the API, contribute your change by completing the steps in [Create a change in Gerrit](https://fuchsia.dev/docs/development/source_code/contribute_changes#create-a-change-in-gerrit), as you would for any Fuchsia source code change.
  - If you have a large change to the API, that is, a change that
    significantly expands on the function of the API or modifies the
    API extensively, do the following:

  - Create an [RFC](https://fuchsia.dev/docs/contribute/governance/rfcs/TEMPLATE) that explains the design of your modification
    to the API.

  - This RFC should be reviewed through the normal
    [RFC process](https://fuchsia.dev/docs/contribute/governance/rfcs/rfc_process). The API reviewer for the relevant area should
    be a stakeholder in the RFC. See the
    [Fuchsia API Council Charter](https://fuchsia.dev/docs/contribute/governance/api_council#area) to identify API reviewers.

  - After your API RFC is approved, contribute your change by completing the
    steps in [Create a change in Gerrit](https://fuchsia.dev/docs/development/source_code/contribute_changes#create-a-change-in-gerrit), as you
    would for any Fuchsia source code change.

- [Request a code review](https://fuchsia.dev/docs/development/source_code/contribute_changes#request-a-code-review) from an API council member.
  Select your API council reviewer based on the area of the Fuchsia API that
  you're modifying. For a list of API council members and their areas of focus,
  see [Membership](https://fuchsia.dev/docs/contribute/governance/api_council#membership) in the Fuchsia API Council Charter.

## Promoting an API

By default, APIs, libraries, etc. are not IDK atoms, not in the IDK/SDK, and not
in an [SDK category](https://fuchsia.dev/docs/contribute/sdk/categories). In order for an API or library to be used
in certain ways, including inclusion in the IDK, it must be made an IDK atom and
assigned an SDK category.

This section describes the process for promoting an atom to the different
categories. These apply to both adding a new atom to a category and promoting
an existing atom from one category to another.

In order for an atom to be added to the IDK/SDK, it must be [promoted to the
`partner` category](https://fuchsia.dev/fuchsia-src/contribute/sdk#promoting-to-partner).

### Promoting an API to the `prebuilt` or `host_tool` category

For an API to be usable by prebuilt binaries or host tools in the Fuchsia SDK,
it must be in the `prebuilt` or `host_tool` [SDK category](https://fuchsia.dev/docs/contribute/sdk/categories),
respectively. The API must follow the
[API evolution guidelines](https://fuchsia.dev/docs/development/api/evolution#evolve-gracefully) which are focused on enabling API
evolution while maintaining compatibility.

Keep in mind that there are additional considerations when
[promoting an API to `partner`](https://fuchsia.dev/fuchsia-src/contribute/sdk#promoting-to-partner), which may reveal
tradeoff decisions between compatibility and long term usability.

Once the API is ready for review, request an [API calibration](https://fuchsia.dev/docs/contribute/governance/api_council#calibration).
Note that API calibration is targeted at *stable* API surface. Category
promotions of libraries only available at `HEAD`, which may occasionally be
necessary when the library is a dependency of another library, may defer
calibration until the API is stabilized.

### Promoting an API to the `partner` category

For an API to be included in the Fuchsia IDK/SDK, it must be in the `partner`
[SDK category](https://fuchsia.dev/docs/contribute/sdk/categories). This requires clearing two hurdles: there must be
a ready and willing customer, and the API must have gone through [API
calibration](https://fuchsia.dev/docs/contribute/governance/api_council#calibration). Note that API calibration is targeted at *stable*
API surface. Promotions to `partner` where the library is marked `stable =
false` do not modify the stable API surface and may defer calibration until the
API is stabilized.
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/contribute/sdk/README.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/contribute/sdk/README.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/sdk/README.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/contribute/sdk/README.md "Edit the source code of this page")