20240624 update - 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 process, 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 process.

Definitions

API releases - overview

To prepare the release of a public 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 alpha releases of Commonalities and ICM (M1).
• M4: the final release-candidate API version ready for meta-release approval, aligned to the final release candidates of Commonalities and ICM (M2), input to subsequent public release.

An API Sub Project can create as many wip, alpha and release-candidate API versions as needed for API development and testing.

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 each release-candidate API versions.
• a release must be created for each public API version.

The release of a public API version is created once the final release candidate is approved for a meta-release.

• Before M4, the release PR with the public 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 of an API version is introduced if/when there are updates to the API (major/minor/patch).

Public releases can have an initial or a stable status: 

• an initial public release indicates that the public 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 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 process as described here: Meta-release Process.

To be part of a meta-release,

• the expected alpha, release-candidate and public API versions need to be (pre-)released
• minimally an initial public release needs to be provided
• each (pre-)release must provide the required set of API release assets according to the API readiness checklist described below. 
• API (pre-)releases are numbered (tagged) using the API release numbering guideline (see below).

Technically, an API release is created using GitHub features and requires:

• A GitHub issue for the release.
• A "release PR" associated to this issue.
• If required (see table below), a GitHub release package (zip file of the whole API Sub Project repository).
• A GitHub release tag with the release number "rx.y" (see below).

Example of the use of the API release process

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

• Develop the 1.1.0 update on the main branch. The first PR updates the version to wip, and the URL to contain vwip.
• Once sufficiently stable, create an alpha release PR that sets the API version to 1.1.0-alpha.1 and will create release rx.1.
• Several alpha API versions may be released, each setting the API version back to "wip" in the first API update PR (rx.2 - rx.m)
• Then (at least) one (or more) release-candidate API versions may be created and released (rx.m+1 - rx.n) 
• The last release-candidate API version will be proposed for public release. 
• For meta-release approval, create the public release PR for the next public API version 1.1.0.
• After meta-release approval, create the release for the new public API version 1.1.0, with its release tag rx.n+1 and release package ("latest")).

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 alpha, release-candidate and public (pre-)release, and for a maintenance release, e.g. rx.y+1.
• After a meta-release of an API 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 new public release shall be rx.y+1. This new public release replaces the previous one 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 ReleaseManagement / documentation repository.

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

• copy the API-Readiness-Checklist.md file(s) to the API Sub Project repository in the home/code folder.
• rename the file to include the prefix <API name> 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 (alpha, release-candidate, initial public release or stable public release)
• 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 alpha release or release candidate may not yet provide all mandatory release assets for the release type.
    
  • update the Comments column with the link to the asset  (if applicable), and any other additional comments as needed
• NOTE: the checklists of a (final) release candidate of an API version and the checklist of its subsequent public release are the same, while additional release assets are required for a subsequent stable public release of the API version.

Checklist explanation

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 addition of a Security review release asset beyond the Commonalities linting rules is for further study.

Release checklist

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
• for public 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.  

API releases - details 

The GitHub release feature

An API release is created using the GitHub PR and release feature (see Draft/publish a new release).

This results in:

• a release tag (with the tag name following the release numbering guidelines below) on the main or on a maintenance release branch, identifying the release number 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 alpha releases.

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

Releasing an API step by step 

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

• 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.
• Create the API release tracker for the target API version as describer here: 20240624 update - API release trackers.

1. On the main branch, develop the API version 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.
2. Once the required stability is reached, create the "release PR" (see details below in the section Create the release PR)
3. 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 tag name shall be 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 API Release Numbering.
   • Outside the project, the release shall be referred to by the API name (for definition see the section on 20240624 update - API versioning) followed by the release number e.g. quality-on-demand rx.y

• Repeat above steps 1, 2 and 3 for
  • alpha releases before M3; the first release candidate is created for M3
  • release candidates between M3 and M4
  • the public release for M4

NOTES:

• An alpha release cannot be proposed for meta-release. It first needs to go to a release candidate.

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 file(s) 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 doing a release)
  • the update of the <API name>-API-Readiness-Checklist.md which confirms the availability of all release assets required 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 all APIs at the top for the most recent release:
    • for an alpha API version, the delta with respect to the previous release
    • for the first release candidate, all changes since the last public release
    • for a 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 (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 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)
  • the formal approval is based on the review of final release-candidate version of the API used for the public release PR
• Approvals shall be documented on the API release tracker page.

Merge the release PR and create the GitHub release

Once approval is obtained, merge the release PR and create the release (the release tag and, optionally, the release package) shall be created using the GitHub release functionality. 

• 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".
• Update the API release tracker with the date and tag of the release to show progress.

Maintain 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

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

For the release of a MAJOR or MINOR update of a publicly released API, the normal API release process (as described above) is applied.

For a MAJOR or MINOR update to a public release rx.y, the next public released is rx+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 rx.y, the next released is rx.y+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-rx.y where rx.y is the release number of the public release rx.y being patched
  • Subsequent patches shall be done on the same maintenance branch, and will increase the y number
• The changes are proposed as usual through Issues, PRs, and commits to this maintenance branch (using wip version)
• After all changes are done, a maintenance release is created for the new public API version x.y.z+1 (per semver 2.0.0) and release number rx.y+1.
• This maintenance release replaces the existing public release of the API in the meta-release.
• The API tracker shall be updated with the new release tag link.
• The PATCH delivered through a maintenance release shall also 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 of the public API version x.y.z+1 (incrementing z) as long as needed.

NOTE: a PATCH is the only case for which a separate branch is created and maintained in the API Sub Project (not counting working branches).

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 API Sub Project, an API Sub Project may contain multiple, closely related APIs. Because a release concerns the whole API Sub Project repository, 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 within the release.

In all cases, each API version shall have its own release tracker (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.