API Release Process

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.

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

Definitions

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:

  • this is the version ready for inclusion in the meta-release (if so planned).

  • the public API version is aligned with the public versions of Commonalities and ICM (M2).

An API Sub Project can release as many alpha and release-candidate API versions as useful for API development and testing. In between releases, the API version is set to "wip" (to indicate that this API version should not be used).

Public API versions 

Public API versions can have an initial or a stable status.

A public API version is released only if it provides all required API readiness checklist items (see: API readiness checklist).

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

To be part of a meta-release, the API Sub Project needs to participate in the meta-release process. For the meta-release, the following needs to be provided:

• the API release tracker (see API release trackers)

• the expected (pre-)releases at the respective M3 and M4 milestones

• minimally an initial public API version

• the required set of API release assets according to the API readiness checklist (see below).

Example of the use of the API release process

To release a MINOR update of a public API version 1.0.0, resulting in the release of public API version 1.1.0:

• Develop the 1.1.0 updates on the main branch. The first PR shall update the OAS file setting the API version to wip, and the URL to vwip.

• Once sufficiently stable, create a release PR for the API version 1.1.0-alpha.1.

• After release PR approval, create the pre-release rx.1 and publish it on the API release tracker.

• Several alpha API versions 1.1.0-alpha.p may be released, each setting the API version back to "wip" in the first API update PR and evolving the alpha number with each following pre-release (rx.2 - rx.m).

• When the API version is ready, create a release PR for the API version 1.1.0-rc.1

• Several release-candidate API versions 1.1.0-rc.q may be released, each setting the API version back to "wip" in the first API update PR and evolving the rc number with each following pre-release (rx.m+1 - rx.n).

• When the API version is ready for public release, create the release PR that sets the public API version to 1.1.0. (this PR minimally removes the rc extensions from the version and URL fields in the API yaml file and assures all API release assets are available as per the API readiness checklist).

• After release PR approval, create the release rx.n+1 and publish it on the API release tracker.

• The approved public API version 1.1.0 will be included in the meta-release as planned.

API release numbering

API release numbers are GitHub tags of the format "rx.y".

The release numbers shall follow the guidelines described below.

• Release numbers start with x=1 and y=1: r1.1.

• y is incremented by 1 at each subsequent (pre-)release (for alpha, release-candidate and public API versions), and for a maintenance release, e.g. rx.y+1.

• After a meta-release of a public API version release rx.y, the next release number for this API is rx+1.1 (y resets to 1).

• In case of maintenance of a release rx.y, the next release shall be rx.y+1.

• A maintenance release replaces the previous release in the meta-release.

The following table illustrates the continuous release numbering of an API version across the API release process.

API readiness checklist

To release an API version, an API Sub Project needs to provide the required release assets as specified in the API Readiness Checklist (see description below).

The template for the checklist is the API-Readiness-Checklist.md file located in the CAMARA / ReleaseManagement / documentation repository folder.

For the readiness of a given API version, an API Sub Project needs to

• copy the API-Readiness-Checklist.md file(s) to the API Sub Project repository in the <home>/documentation/API_documentation folder.

• rename the file to include <API name> as prefix plus a dash ("-") e.g. quality-on-demand-API-Readiness-Checklist.md

• provide each release asset as indicated in the column corresponding to the release type

• for an available asset

  • update the Status column with "Y" (yes) if the release asset is available or fulfilled in the current release, or "N" (no) otherwise. Example: an intermediate pre-release may not yet provide all mandatory release assets for the release type.

  • update the Reference Information column with the relative link to the asset in the repository (if applicable), and any other additional links or comments as needed (see explanations below).

NOTE: the checklists of a public API version and of its preceding release-candidate API version can be the same.

Checklist explanation

The following table explains each of the release assets expected to be delivered in the API release.

Note: the addition of a Security review release asset beyond the Commonalities linting rules is for further study.

Readiness checklist per API version

The following table is the API readiness checklist that lists the assets that need to be provided with the API version for it to be ready for its (pre-)release. The required assets depend on 

• the API version type: alpha, release-candidate or public

• for public API versions, in addition, depending on its target status: initial or stable

In the table, 

• "M" indicates a mandatory release asset

• "O" indicates an optional release asset which may be provided with the release, if available.  

The API-Readiness-Checklist.md is available in the ReleaseManagement / documentation for copying to the API Sub project’s documentation / API documentation folder. When copying, the file shall be prefixed with the api-name as there shall be one checklist for each API of the API Sub Project (resulting in <api-name>-API-Readiness-Checklist.md).

Explanations on the above table

• The Status column shall contain "Y" (yes) if the release asset is available or fulfilled in the current release, or "N" (no) or "tbd". Example use of "tbd" is in case an alpha or release-candidate API version does not yet provide all mandatory assets for the release.

• The Reference information column, provide the links to the release asset once available, the applicable release numbers (not versions) of Commonalities and ICM, and any other relevant links or information.

• For the point 12: you can put a reference to a comment that you write under the table with the involved companies and copy the following link if your previous public API version has been certified:: GSMA OGW Portal.

Note: the checklists of a public API version and of its preceding release-candidate API version can be the same.

API releases - details 

The GitHub release feature

Technically, an API (pre-)release is created using the GitHub release feature (see Draft/publish a new release). It involves

• A GitHub issue defining the scope of the target API version.

• A release PR associated to this issue.

After release PR approval: 

• a release tag (with the tag name following the API release numbering guidelines above) on the main or on a maintenance release branch.

• a release package containing the API's repository with the corresponding API release assets for each contained API version (zip file). A release package is optional for pre-releases of alpha API versions.

A GitHub release is the combination of a release tag and, optionally, a release package created using the GitHub release feature for an API repository. A GitHub release may not contain any wip APIs versions.

Releasing an API step by step 

This section gives the overview of the steps to release a public version of an API. 

• Create a GitHub issue defining the scope of the API version targeted to be released. Descriptive information in this issue can be reused in the changelog/release notes.

• Create the API release tracker for the targeted public API version as describer here: API release trackers.

• On the main branch, develop the API version scope in a "work-in-progress mode" (API version = wip and version in URL is vwip).

  • several pre-releases for one or more alpha API versions may be created between M1 and M3

• To reach M3, a release PR needs to be created that updates the API to become the first release-candidate API version, including the relevant release assets (see details in section Create the (pre-)release PR below) 

• Further pre-releases of one or more release-candidate API versions may be created between M3 and M4

• To reach M4, a release PR needs to be created that updates the API to become the first public API version, including the relevant release assets (see details in section Create the (pre-)release PR below)

• During above development (M1-M3) and test (M3-M4), make sure to create and record the required release assets according to the API-Readiness-Checklist.

• To release the API, manage the release PR approval, merge the approved release PR and create the release (see below).

NOTE: To be included in the meta-release, the release of the public API version needs to be available.

Prepare the API release

To create a (pre-)release of the API, a release PR (linked to the associated release scope issue) must be created.

A release PR does not change the content the repository other than the following changes:

• the update of the version information in the API OAS definition file(s) within the repository (Info/version field and URL version)

  • no API in the repository shall contain “wip” in the version field in the API OAS definition file

  • at least the version of one API must be changed with respect to the previous release (otherwise there is no sense in doing a release)

• the update of all links (URLS) to point to resources in the release and hence include the release number on their path (no links with "main", no relative links).

• the update of the API-Readiness-Checklist.md for each API in the repository which confirms the availability of all release assets required for the (pre-)release. For details, see the explanations on the API readiness checklist above.

• the update of the Changelog.md in the repository with new content on all APIs at the top for the most recent (pre-)release as follows:

  • for an alpha release, the delta with respect to the previous release

  • for the first release-candidate, all changes since the last public release

  • for subsequent release-candidate(s), only the delta to the previous release-candidate

  • for a public release, the consolidated changes since the previous public release

• the update of the README.md (as necessary)

Manage the release PR approval

A  release PR has to be approved before the code owner is allowed to merge as follows:

• alpha API versions: by one other code owner (as for any PR)

• release-candidates: by the majority of the API Sub Project Maintainers + one Release Manager

• public API versions:

  • by the majority of the API Sub Project Maintainers (normally given, if the preceding release-candidate was approved), and

  • by the TSC (to be discussed how this will be done formally)

  • the formal approval is based on the review of the release PR for the public API version 

• Approvals shall be documented as reviews in the release PR in GitHub.

Merge the release PR and create the GitHub release

Once approval is obtained, merge the release PR and create the GitHub release: 

• The GitHub release package is (optionally) created using the GitHub release feature.

• The release tag shall be named with the next release number and shall have the following format: rx.y

  • The x.y number shall follow the release numbering scheme as defined in the above section on Release Numbering.

  • Note: Outside the project, the release shall be referred to by the API repository name (for definition see the section on API versioning) followed by the release number e.g. quality-on-demand rx.y

• The release description shall be copied from the CHANGELOG.md (as described above)

• For releases with alpha and release-candidate API versions, tick the "Set as a pre-release" box; for public or maintenance releases, tick "Set as latest release".

Track the release

• Update the API release tracker with the date and tag of the (pre-)release to show progress.

Updating a public release

An update of a publicly released API needs to be carefully planned. This is especially true for updates that concern breaking changes, but also non-breaking changes, such as new optional functionality. Such updates shall be widely announced and discussed with API consumers.

To update a public API, a next public release of this API needs to be created including the (MAJOR/MINOR/PATCH) update(s).

• MAJOR or MINOR updates shall be handled through the API release process as described above

• PATCH updates can be done at any time after the public API release, and as long as the API is not retired. However, once there is a stable API version, one would preferably push for adoption of the stable API, rather than patching previous initial API versions.

MAJOR or MINOR updates

Breaking (MAJOR) or non-breaking (MINOR ) updates to a public API version shall result in a new version of that API.

To release a MAJOR or MINOR update of a publicly released API, the normal API release process (as described above) is applied, including the creation of a dedicate API release tracker for this new API version.

For a MAJOR or MINOR update to a public release rm.n, the next public released is rm+1.n.

PATCH update

A PATCH to a public release is done using a dedicated maintenance branch.

For a PATCH update to a public release rm.n, the next released is rm.n+1. The new public API version will be vx.y.z+1

A shorter release process is applied as follows:

• A dedicated maintenance branch shall be opened to develop the PATCH of the API

  • the branch name shall be maintenance-rm where m is the first number of the public release rm.n being patched

  • Subsequent patches shall be done on the same maintenance branch, and will increase the n number.

• The changes are proposed as usual through Issues, PRs, and commits to this maintenance branch (using wip version)

• It is assumed that no intermediate pre-releases are created, however, if needed for the development of the patch; this can be done and should be tracked on the existing API release tracker.

• After all changes are done, a release PR for the patched public API version shall be created. In this release PR, the API version shall be set to x.y.z+1 (per semver 2.0.0) and maintenance release number rm.n+1 shall be used.

• After approval, the maintenance release is created for the new public API version x.y.z+1 (per semver 2.0.0) with release number rm.n+1.

• This maintenance release replaces the existing public release of the API in the meta-release.

• The API release tracker of the API version shall be updated with the maintenance release tag link and date. Also the name of the API release tracker shall be updated to reflect the patch version.

• The PATCH delivered through a maintenance release shall be merged into a next MAJOR or MINOR API release on the main branch.

• The maintenance branch shall continue to exist for further PATCH updates (release rm.n+2, rm.n+3, etc.) of the public API version x.y.z+1 (incrementing z) as long as needed, and be reflecting on the API release tracker.

NOTE: a PATCH is the only case for which a separate branch is created and maintained in the API repository (as pull requests should be prepared within forks of the API repository, c.f. Governance/CONTRIBUTING.md)

Multiple APIs in one release

Although it is highly recommended to develop each API in its own repository, an API repository may contain multiple, closely related APIs. Because a release concerns the whole API repository, this will result in releasing multiple APIs in one release. In this case, an API version can only be released if all contained APIs provide the required set of public release assets. The API release must not contain any API with a wip version.

In all cases, each API version shall have its own release tracker (on the wiki under the Sub Project's API Release Tracking page), and, in this case of multiple APIs in the same release, the same release tag will appear in multiple API release trackers.