FOR REVIEW
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.
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 cycle.
Definitions
| Term | Definition |
|---|---|
release | The release of an API version consists in the creation of a GitHub release of the API's repository, with a release tag and (optionally for alpha) a release package. A release can be created for any alpha, release-candidate or public-release API version. No releases are created for wip API versions. |
pre-release | The term pre-release is used to refer to the release of any of the alpha or release-candidate API versions. NOTE: 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. |
meta-release | A meta-release is a set of public-release API versions made available at a given point in time (Spring and Fall). All API versions of a given meta-release shall be aligned to the Commonalities and Identity and Consent Management public-releases included in that same meta-release. |
release tag | A release tag is a GitHub tag placed on the main or a maintenance branch to allow locating the corresponding API version in the repository. |
| release package | A release package is a zip file of the repository created using the GitHub release mechanism together with the release tag. It contains a snapshot of the full API Sub-project repository with the content indicated by the release tag. |
What is an API release ?
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.
It is up to the API Sub-project to decide if/when to create a pre-release for an alpha or release-candidate API version.
When planning to deliver a public-release API version into a meta-release, certain pre-releases are expected to be made available during the meta-release cycle, along with the related set of release assets. The expected and optional pre-releases are described below.
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). This is optional for intermediate alpha releases.
API releases are numbered (tagged) following the API release numbering guideline (see below).
How to create an API release ?
To create an API release, a "release PR" (linked to the associated PR issue) needs to 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 left with “wip” within the version in the API OAS definition file
- at least the version of one API will be changed (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: API Release Process
- 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)
- the update of the version information in the API OAS definition files within the repository
- 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 sub project Maintainers + one Release Manager
- public-releases:
- by the majority of the 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: public-release should have a formal approval, the actual review is done based on the release-candidate versions of the APIs.
- Directly after the PR is merged, the release tag will be created with the GitHub release functionality ("Draft/publish a new release")
- The release description will be copied from the CHANGELOG.md (the newly added part)
- For releases with alpha and release candidate version use "Set as a pre-release", for public-releases "Set as latest release"
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.
| API version | release tag | release package | release package tag |
|---|---|---|---|
| work-in-progress | N/A | N/A | N/A |
| alpha | rx.1 ... rx.m | optional (exception: mandatory for M3 milestone) | optional [ "pre-release" ] |
| release-candidate | rx.m+1 ... rx.n | mandatory | "pre-release" |
| public-release | rx.n+1 | mandatory | "latest" |
For an API released with rx.y, when preparing the next meta-release, the release numbering starts at rx+1.0.
API readiness checklist
NOTE: The API readiness checklist .md file which can be copied for API sub-projects will 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 availability of the release assets needs to be recorded in the API readiness checklist .md file(s) in the API Sub-project repository.
- There needs to be one API readiness checklist per API, updated for each API version.
- There is a different API readiness checklist for Sandbox API Sub-projects than for Incubated API Sub-projects.
The following table explains each of the release assets expected to be delivered.
Nr | API release assets | Explanation |
1 | API definition | This is the OAS API definition file (following the https://spec.openapis.org/oas/v3.0.3 format). It shall be present in the home/code/API_definition folders of the API Sub-project and validated using the linting rules in point 6. |
2 | Design guidelines from Commonalities applied | This corresponds to a set of linting rules provided by Commonalities that are successfully executed against the OAS API definition file. Other guidelines that cannot be verified by linting rules should be listed by the Commonalities team, in particular data type alignment to the Commonalities/artifacts/CAMARA_common.yaml |
3 | Guidelines from ICM applied | This corresponds to a set of linting rules provided by ICM that are successfully executed against the OAS API definition file. Other guidelines that cannot be verified by linting rules should be listed by the ICM team |
| 4 | API versioning convention applied | This shall be checked through a linting rule added to the Commonalities rule set on the format of the version field in the OAS API definition file. |
5 | API documentation | The API specification shall include all the needed documentation. It shall include the section on security as described in the API Design Guidelines API documentation beyond the one embedded in the API definition file, shall be located in the home/documentation/API_documentation folder of the API Sub-project. It shall follow the Commonalities/documentation/API-DocumentationTemplate.md |
6 | User stories | User Stories (it is recommended to have at least 2) 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. |
7 | Basic API test cases & documentation | At least one Gherkin feature file is provided for the API in the Test_definitions folder of the API Sub-project covering sunny day scenarios. |
8 | Enhanced API test cases & documentation | Gherkin feature files are provided for the API in the Test_definitions folder of the API Sub-project covering sunny and rainy day scenarios |
9 | Test result statement | A statement in a discussion issue of teh API Sub-project by at least one of the API Sub-project members that the Gherkin feature files have been successfully executed against their (lab) API implementation |
10 | API release numbering conventions applied | This is verified using the information on the release tracker page. |
11 | Change log updated | Change log need to be provided following the template and are located here: Commonalities/documentation/SupportingDocuments/CHANGELOG_TEMPLATE.md . |
12 | Previous initial public-release API version had at least 1 certified implementation | Reference to at least 1 certification of the API is provided on the GSMA API certification page. |
Note: the following Security review release asset beyond the Commonalities linting rules is left for further study.
The following table is the API readiness checklist of the assets that need to be provided for the release of an given API version.
In the table, "M" indicates a mandatory release asset, and "O" indicates an optional release asset which may be provided with the release if available.
Nr | API release assets | alpha | release-candidate | public-release | |
initial | stable | ||||
1 | API definition | M | M | M | M |
2 | Design guidelines from Commonalities applied | O | M | M | M |
3 | Guidelines from ICM applied | O | M | M | M |
| 4 | API versioning convention applied | M | M | M | M |
5 | API documentation | M | M | M | M |
6 | User stories | ||||
7 | Basic API test cases & documentation | O | M | M | M |
8 | Enhanced API test cases & documentation | O | O | M | M |
9 | Test result statement | O | O | O | M |
10 | API release numbering convention applied | M | M | M | M |
11 | Change log updated | M | M | M | M |
12 | Previous initial public-release API version had at least 1 certified implementation | O | O | O | M |
To be part of a meta-release, minimally the initial release assets need to be provided.
In the table, "M" indicates a mandatory release asset, and "O" indicates an optional release asset which may be provided with the release if available.
Nr | API release assets | alpha | release-candidate | public-release | Explanation | |
initial | stable |
| ||||
1 | API definition | M | M | M | M | This is the OAS API definition file (following the https://spec.openapis.org/oas/v3.0.3 format). It shall be present in the home/code/API_definition folders of the API Sub-project and validated using the linting rules in point 6. |
2 | Design guidelines from Commonalities applied | O | M | M | M | This corresponds to a set of linting rules provided by Commonalities that are successfully executed against the OAS API definition file. Other guidelines that cannot be verified by linting rules should be listed by the Commonalities team, in particular data type alignment to the Commonalities/artifacts/CAMARA_common.yaml |
3 | Guidelines from ICM applied | O | M | M | M | This corresponds to a set of linting rules provided by ICM that are successfully executed against the OAS API definition file. Other guidelines that cannot be verified by linting rules should be listed by the ICM team |
| 4 | API versioning convention applied | M | M | M | M | This shall be checked through a linting rule added to the Commonalities rule set on the format of the version field in the OAS API definition file. |
5 | API documentation | M | M | M | M | The API specification shall include all the needed documentation. It shall include the section on security as described in the API Design Guidelines API documentation beyond the one embedded in the API definition file, shall be located in the home/documentation/API_documentation folder of the API Sub-project. It shall follow the Commonalities/documentation/API-DocumentationTemplate.md |
6 | User stories | User Stories (it is recommended to have at least 2) 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. | ||||
7 | Basic API test cases & documentation | O | M | M | M | At least one Gherkin feature file is provided for the API in the Test_definitions folder of the API Sub-project covering sunny day scenarios. |
8 | Enhanced API test cases & documentation | O | O | M | M | Gherkin feature files are provided for the API in the Test_definitions folder of the API Sub-project covering sunny and rainy day scenarios |
9 | Test result statement | O | O | O | M | A statement in a discussion issue of teh API Sub-project by at least one of the API Sub-project members that the Gherkin feature files have been successfully executed against their (lab) API implementation |
10 | API release numbering convention applied | M | M | M | M | This is verified using the information on the release tracker page. |
11 | Change log updated | M | M | M | M | Change log need to be provided following the template and are located here: Commonalities/documentation/SupportingDocuments/CHANGELOG_TEMPLATE.md . |
12 | Previous initial public-release API version had at least 1 certified implementation | O | O | O | M | Reference to at least 1 certification of the API is provided on the GSMA API certification page. |
To
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 aligned to the Commonalities and ICM M1 release.
- M4: the final release-candidate API version ready for meta-release approval, aligned to the Commonalities and ICM M2 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, 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, the corresponding release tag and the release package shall provide all relevant rc 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.
IMPORTANT
API pre-releases (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 are created in line with the target maturity status of the API version.
- Inclusion in the meta release is done by updating the API release tracker with the date and tag of this release.
A next public-release API version is introduced if there are updates to the API (major/minor/patch).
API meta-release
To be approved for meta release
- 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 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 the release tag and release packages
- Finally the API Sub-project shall update the API release tracker accordingly.
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 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 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.
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 for 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)
- Based on the last release-candidate API version and its release assets, the PR for the new public-release API version shall be proposed for meta-release.
- After meta-release approval, create the public release for the new public-release API version 1.1.0, with its release tag rx+1.n 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, without necessarily waiting for the next meta-release.
- The patch update is prepared on a dedicated maintenance branch which needs to be created 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 for minor/patch.
- 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.
- 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 APIs, which will result in release multiple APIs in one release. For this case, a public-release can only be created if each contained API provides the required set of public-release assets.
In all cases, each API shall have its own release tracker page, and, in this case, the same release tag will appear in multiple API release trackers.