API Release Process

The Release Management process targets the creation of public-releases of API versions, aligned with the Commonalities and ICM release in a given meta-release.

In the meta-release cycle, this API release process describes how to prepare the public-release of an API version.

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

Definitions

API releases

In preparation of a public-release API version, an API Sub Project can create many wip, alpha and release-candidate API versions during the API development. The API versioning is done as described in the API versioning guidelines here: API versioning. 

The API Sub Project creates a release for an API version as follows:

• a pre-release may be created for any alpha API version. 
• a pre-release must be created for release-candidate API versions.
• a pubic release must be created for public-release API versions

public-releases can have an initial or stable status: 

• an initial public-release indicates that the public-release API version is the result of rapid development and is still unstable, e.g. API versions with a v0.x.y version number.
• a stable public-release indicates that the public-release API version is stable and will be maintained.

When planning to deliver a public-release API version into a meta-release, the API Sub Project needs to participate in the meta-release cycle, and provide expected releases according to the meta-release process described here: Meta-release Process. To be part of a meta-release, minimally an initial public-release need to be provided.

Each release must provide the required set of API release assets according to the API readiness checklist described below. 

Technically, an API release is created using the GitHub pull request (PR) (with associated GitHub issue) and repository release features, and results in the creation of a GitHub release tag and, if required, a GitHub release package (zip file of the API Sub Project repository).

API releases are numbered (tagged) using the API release numbering guideline (see below).

API release numbering

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

IMPORTANT: Release numbers are not related to the API version.

The release numbers shall follow the guidelines described below.

• Release numbers start with x=0 and y=1: r0.1.
• y is incremented by 1 at each subsequent alpha, release-candidate and public-release, and for a maintenance release, e.g. rx.y+1.
• After a meta-release of an API through release rx.y, the next release number for this API is rx+1.0 (y resets to 0).
• In case of maintenance of a release rx.y, the new public-release shall be rx.y+1.

Example of continuous release numbering across the API version.

For an API released with rx.y, when preparing the next meta-release, the release numbering starts at rx+1.0.

How to create an API release ? 

An API release is created using the GitHub PR and release features and results in:

• a release tag (following the release numbering guidelines below) on the main or on a maintenance release branch, identifying the release of the API version.
• a release package containing the API's repository with the corresponding API release assets for the released API version (zip file). This is optional for intermediate alpha releases.

API releases are numbered (tagged) following the API release numbering guideline (see above).

Releasing an API step by step 

1. Create a GitHub issue defining the scope of the targeted API release. Descriptive information in this issue can be reused in the changelog/release notes. All discussions wrt to this release shall be handled through this issue.
2. Create the API release tracker for the target API version as describer here: API release tracking process.
3. On the main branch, develop the API scope in a "work-in-progress mode" (API version = wip and version in URL is vwip).
   • during development and test, make sure to create and record the required release assets according to the API-Readiness-Checklist file
4. Once the required stability is reached, create the "release PR" (see details here: CreatethereleasePR

5. Manage the "release PR" approval, merge the approved "release PR" and create the release

   • • An API release is created using the GitHub release feature.
     • The release name shall be the same as the release tag and shall have the following format: rx.y
     • The x.y number shall follow the release numbering scheme: APIreleasenumbering
     • Outside the project the release name shall be the API name (for definition see API versioning#APIname) combined with the release number e.g. qod rx.y

Repeat step 3, 4 and 5 for

• • alpha releases up to the M3 milestone
  • release-candidates between the M3 and the M4 milestone,
  • finishing with the public-release for inclusion in the meta-release 

Create the release PR

To create an API release, first a "release PR" (linked to the associated PR issue) must be created to do a release of the API's repository:

• The “release PR” does not change the content of what is in the repository except the following points.
• The “release PR” provides (only) the following changes:
  • the update of the version information in the API OAS definition files within the repository
    • no API in the repository shall contain “wip” within the version field in the API OAS definition file
    • at least the version of one API will be changed with respect to the previous release (otherwise there is no sense in having a release)
  • the update of the <API name>-API-Readiness-Checklist.md which confirms the availability of all required release assets as defined for the release type. For details, see the explanations on the API readiness checklist below.
  • the update of the Changelog.md in the repository with new content on the top for each changed API:
    • the delta to the previous release for an alpha API version
    • for the first release-candidate, all changes since the last public-release
    • for the subsequent release-candidate, only the delta to the previous release candidate
    • for the public-release, the consolidated changes since the last public-release
  • the update of the README.md (if necessary)

Manage the release PR approval

• A  “release PR” has to be approved before the code owner is allowed to merge as follows:
  • alpha releases: by one other code owner (as for any PR)
  • release-candidates: by the majority of the API Sub Project Maintainers + one Release Manager
  • public-releases:
    • 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)
  • NOTE: a public-release should have a formal approval, the actual review is done based on the release-candidate versions of the APIs.

Merge the release PR and create release

• Directly after the PR is merged, the release (the release tag and optionally the release package) shall be created using the GitHub release functionality ("Draft/publish a new release")
  • The release description shall be copied from the CHANGELOG.md (as described above)
  • For releases with alpha and release-candidate API versions, use "Set as a pre-release", for public-releases "Set as latest release".

API readiness checklist

The API-Readiness-Checklist.md file to be copied by API Sub Projects is be provided in the Release Management repository (link tbd).

An API version for which a release is created needs to provide the related set of release assets. The APi Sub Project needs to

• copy the <API name>-API-Readiness-Checklist.md file(s) to the API Sub Project repository in the home/code folder.
• rename the file to include the <API name>
• record the availability of each release asset in the file
• there needs to be one API readiness checklist file per API, updated for each API version.
• for public-release API versions, there is a different API readiness checklist for initial and stable releases.

Explanations

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

Note 1: User Stories are being handled when submitting an API to the API backlog (see here). It is recommended to have at least 2 user stories, which need to be documented by the API Sub Project team. User Stories shall follow the template: Userstory-template.md and be located in the home/documentation/API_documentation folder of the API Sub Project.

Note 2: the Security review release asset beyond the Commonalities linting rules is left for further study.

Checklist per API version type

The following table indicates the assets of the API readiness checklist that need to be provided for the release of an API version depending on 

• its version type: alpha, release-candidate or public-release
• for public-types, 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.  

API pre-releases

To prepare a public-release API version, at least two intermediate API versions must be (pre-)released as follows:

• M3: the first release-candidate API version implementing the defined API scope for the release (achieved through one or more alpha releases), agreed stable for functional testing and aligned to the Commonalities and ICM (M1) alpha releases.
• M4: the final release-candidate API version ready for meta-release approval, aligned to the Commonalities and ICM (M2) final release-candidate releases, input to subsequent public-release.

Additional pre-releases can be created by an API Sub Project as they see fit.

pre-release of an alpha API version

• To create a pre-release of an alpha API version (a.k.a. an alpha release), the corresponding release tag and, optionally, the release package shall provide all relevant alpha assets of the API readiness checklist.
• An alpha API version cannot be proposed for meta-release. It first needs to go to a release-candidate API version.

pre-release of a release-candidate API version

• To create a pre-release of a release-candidate API version (a.k.a. a release-candidate), the corresponding release tag and the release package shall provide all relevant release-candidate assets of the API readiness checklist.
• When a release-candidate API version is proposed for meta-release, the public-release API version PR needs to be prepared. 
• This public-release API version PR needs to go through TSC approval in order for the API version to be included in the meta-release.

API public-release

A public-release API version is created when the final release-candidate API version is approved for a meta-release.

• Before M4, the release with the public-release API version and all public-release assets are created in line with the target maturity status of the API version: initial or stable.
• Inclusion in the meta-release is done by updating the API release tracker with the date and tag of this public-release

A next public-release API version is introduced if/when there are updates to the API (major/minor/patch).

API approval for meta-release

To be approved for meta-release

• Before M4, the API Sub Project shall announce their readiness for public-release of an API version by adding the PR for the public-release API version on their API release tracker page.
• After check by the Release Management team, approval of the public-release PR is requested to the TSC.
• The TSC shall document their approval on the API release tracker.
• Once approved, the API Sub Project shall commit the public-release API version PR, create its release tag and release package
• Finally the API Sub Project shall update the API release tracker with the API public-release tag.

Updating a public-release API

An update of a public-release 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.

Releasing breaking or non-breaking updates

Breaking (major) or non-breaking (minor functional) updates to a public-release API, shall result in a new release of that API in the next meta-release.

• The development of the update(s) is done against the main branch.
• The same pre-release and public-release steps apply at the meta-release cycle milestones.
• The next release numbering starts at rx+1.1 with respect to the previous public-release rx.y.
• The updated API shall be released in the next meta-release, following the normal API release process, with final release number rx+1.n

Maintenance release

Once an API has been published as part of a meta-release, situations may occur where minor or patch changes to this API need to be made, without necessarily waiting for the next meta-release.

• The patch update of a released API is prepared on a dedicated maintenance branch. This branch will continue to exist until its updates are integrated into the main branch.
• A new public-release may be created immediately without waiting for the next meta-release.
• The release number in case of maintenance of a release rx.y, shall be rx.y+1
• The availability of the new release shall be managed through the API's release tracker page (reflecting the planning, the progress status and the final result)
• A patch release replaces the released API version in the existing meta-release.

Multiple APIs in one release

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

In all cases, each API version shall have its own release tracker, and, in this case, the same release tag will appear in multiple API release trackers.