/
API Release Process

API Release Process

Owned by Tanja de Groot
Last updated: Jan 07, 2025
17 min read

The API Release Process describes the creation of (pre-)releases of API versions throughout the API lifecycle, and for a given meta-release.

For a meta-release, the API Release Process targets the release of public API versions, aligned with the corresponding Commonalities and ICM public versions.

IMPORTANT

API release numbers are decoupled from API version numbers.

API releases are just numbered sequentially, while API versions follow the API versioning guidelines.

 The following sections describe how to create an API release and how to report progress on it during the meta-release process.

Definitions

Term

Definition

Term

Definition

pre-release

A pre-release is a GitHub release of an alpha or release-candidate API version. Note: the term release is also often used here but it should be clear from the context.

NOTE: pre-releases are not meant to be included in a meta-release. All pre-releases are publicly available in the CAMARA GitHub and can be used AT THE USER'S OWN RISK, as changes may happen to such API versions without notice.

release

A release is a GitHub release of a public API version. Releases may be proposed as part of a meta-release.

release of initial

 

public API

Initial public API versions only exists for new APIs. It concerns public APIs versions with x = 0 (0.y.z without version extension).

A public API version is called "initial" to indicate that the API version has not yet reached full maturity, but is considered stable enough to  be proposed for use in applications. However, the user shall be aware that subsequent versions of this API may require code changes to their applications.

Initial public API versions can be

  • released outside the meta-release process in order to allow for rapid evolution.

  • released as part of a meta-release, after which it is expected that in the next meta-release this API version becomes stable.

release of stable public API

Stable public API versions are recommended for use in commercial applications. The user can expect that subsequent public API versions will be backward-compatible with the one they are using, unless explicitly announced otherwise.

meta-release

A meta-release is a set of public API versions published together at a given point in time (Spring and Fall).

All API versions of a given meta-release shall be aligned to the releases of the Commonalities and Identity and Consent Management (ICM) documentation included in that same meta-release.

maintenance release

A maintenance release is the release of a patch update of a public API version.

release tag

A release tag is a GitHub tag placed on the main or a maintenance branch that identifies a release in the API's repository.

release package

A release package is a zip file of the GitHub repository created using the GitHub release mechanism. It contains a snapshot of the full API repository marked with the release tag.

GitHub release

A GitHub release is the combination of a release tag and, optionally, a release package of the GitHub repository (zip file) created using the GitHub release feature. A GitHub release applies to the full API repository. A GitHub release may containing any alpha, release-candidate or public API version(s). A GitHub release shall not include any wip API versions.

release PR

A release PR is created for an API version to prepare its GitHub release. A release PR shall minimally set the version fields in the API yaml file to the exact API version and establish the availability of the API release assets as per the API readiness checklist.

API release tracker

An API release tracker is a LF Confluence wiki page that provides the visibility on the progress of the (pre-)releases of a given API version. Each public API version planned for release by an API Sub Project shall have its release tracker under their API Sub Project's API Release Tracking page.

API releases - overview

To prepare the release of a public API version, API versions shall be (pre-)released as follows:

  • before M3, release one or more alpha API versions as needed

  • to reach M3, release the first release-candidate API version:

    • the release-candidate implements the scope of the target public API version.

    • this pre-release is agreed as ready for API implementation and functional testing.

    • it is aligned with the release-candidate versions of Commonalities and ICM (M1).

  • between M3 and M4, release one or more release-candidate API versions as needed

  • to reach M4, release the public API version: