FOR REVIEW
The Release Management process targets the creation of public releases of APIs, aligned with a given Commonalities and ICM release, in a given meta-release.
In the meta-release cycle, the process requires, to prepare for public release of an API,
IMPORTANT
API release numbers are decoupled from API version numbers.
API releases are just numbered sequentially, while API versions follow the API versioning guideli.nes.
The following sections describe how to plan an API release and how to report progress on it.
What is an API release ?
An API Sub-project can create as many initial, alpha and release-candidate API versions during the life cycle of the API. API versioning is done as described in the API versioning guidelines here API versioning.
The decision to release a given version of an API is up to the API Sub-project. However, when planning to deliver a public-release API version into a meta-release, certain pre-releases are expected for the API during the meta-release cycle, along with the related set of release assets. These expected pre-releases are described below.
How to create an API release ?
An API release is created using the GitHub release feature and results in:
- a release tag (following the release numbering guidelines below) on the main or on a maintenance release branch, identifying the set of release assets for the API version to be released.
- a release package containing the corresponding API release assets for the released API version (zip file).
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=0 and y=1: r0.1
- y is incremented by 1 at each subsequent initial, alpha, release-candidate and public release, and for a maintenance release, e.g. rx.y+1
- After a meta-release for an API through release rx.y, the next release number is rx+1.0 (y resets to 0)
- In case of maintenance of a release rx.y, the new release shall be rx.y+1
Example of continuous release numbering across
| API version | release tag | release package | release package tag |
|---|---|---|---|
| initial (x=0) | r0.1 ... r0.m | optional | optional [ "pre-release" ] |
| alpha (x>=0) | rx.m+1 ... rx.n | optional | optional [ "pre-release" ] |
| release-candidate (x>=0) | rx.n+1 ... rx.p | mandatory | "pre-release" |
| public-release (x>=0) | rx.p+1 | mandatory | "latest" |
| work-in-progress | N/A | N/A | N/A |
| next release for meta starts at | rx+1.0 | as per above | as per above |
For an API released with rx.y, when preparing the next meta-release, the release numbering starts at rx+1.0.
API release assets checklist
API pre-releases
To prepare the public-release API version, at least two intermediate API versions must be (pre-)released as follows:
- M3: the final alpha API version implementing the defined API scope for the release, agreed stable for functional testing and ready to be alignment to the Commonalities and ICM M2 release.
- M4: the final release-candidate API version ready for meta-release approval.
Addition pre-releases can be created by an API Sub-project as they see fit.
IMPORTANT
API pre-releases (initial, alpha or release-candidate) available in the CAMARA GitHub can be freely used, BUT AT THE USER'S OWN RISK.
API public-release
A public-release API version is created when the final release-candidate API version is approved for a meta-release.
- M5: the release with the public-release API version and all public-release assets is created.
- Inclusion in the meta release is done by updating the API release tracker with the date and tag of this release.
A public-release API version may be either
- a Sandbox release
- an Incubated release
The terms Sandbox and Incubator intent to reflect the level of maturity of the public-release API version and will have different sets of API release assets.
Sandbox release
A Sandbox release concerns an API that has not yet reached full maturity, but is considered stable enough to have a public-release as part of a meta-release. It is expected that in the next meta-release the API version become Incubated.
A Sandbox release may concern a public-release API version with x=0. e.g. 0.10.0.
Incubator release
An Incubator release is any stable public-release API version which has been deployed by at least 2 operators (as per the release asset checklist).
API meta-release
To be approved for meta release
- The proposed API release must provide all the public release assets of the release checklist
- The API Sub-project shall announce their readiness for public-release of an API by adding the relevant release-candidate API version on their API release tracker page.
- After check by the release management team, approval is documented on the API release tracker.
- Once approved the API Sub-project shall create the public release (final public-release API version, release tag and release packages) and update the API release tracker.
Updating a public-release API
An update of a 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 shall be widely discussed.
Releasing breaking or non-breaking updates
Breaking (major) or non-breaking (minor) 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, and the same pre-release and public release steps apply at the meta-release cycle milestones.
The release numbering starts at rx+1.1 with respect to the previous public-release.
Example for a non-breaking update of a public-release API version 1.0.0, resulting in a new release with API version 1.1.0:
- Develop the 1.1.0 update on the main branch
- Once sufficiently stable, create release rx+1.1 with API version 1.1.0-alpha.1
- Create pre-releases for additional alpha API versions as needed, with or without release packages
- Create pre-releases for one or more release-candidate API versions (release tag + release package)
- The last pre-release of the release-candidate API version will be proposed for meta-release.
- After meta-release approval, create the public release for the new public-release API version 1.1.0 with release tag and release package ("latest")).
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.
- In this case a dedicated maintenance branch will be opened for the maintenance of the API.
- The changes are proposed through Pull Request (PRs) and committed to the maintenance branch.
- The version of the resulting updated API shall follow the semver rules.
- 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 should be reflected through the API release tracker page.
Multiple APIs in one release
One API Sub-project may release multiple APIs in one release, but the public-release can only be created if each API provides the required set of public release assets.
Each API shall have its own release tracker page, and, in this case, the same release tag will appear in multiple trackers.