The Release Management process targets the creation of public-releases 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.
...
| 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 public API version. No releases can be 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. |
alpha - release | The term alpha - release is used to refer to the release of an alpha API version. |
release - candidate | The term release - candidate is used to refer to the release of a release-candidate API version.public-release |
public release | The term public - release is used to refer to the release of a public -release API version. It can have the status initial status initial or stable. |
initial public-release | An initial public - release only exists for new APIs. It concerns the release of public -release APIs versions with x = 0 (0.y.z without version extension). A public - release is called "initial" to indicate that the API version has not yet reached full maturity, but is considered stable enough to be to be proposed for use in commercial applications. However, but the user shall be informed that subsequent API versions may require code changes to their applications. Initial public - releases can be
|
stable public-release | A stable public - release concerns an API version released after its stability has been demonstrated through
Stable public -release releases concern the API versions are the ones 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 | A meta-release is a set of public -releases of API versions made available released at a given point in time (Spring and Fall). All API versions of a given meta-release shall be aligned to the public releases of the Commonalities and Identity and Consent Management (ICM) public-releases documentation included in that same meta-release. |
maintenance - release | The term maintenance - release is used to refer to the release of a patch update of a released public -release API version. |
release tag | A release tag is a GitHub tag placed on the main or a maintenance branch that identifies a release of the API version's 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. |
| API release tracker | An API release tracker is a page that provides the visibility on the progress of the release of a given API version. All API versions released Each API version under release by an API Sub Project shall have a its tracker under their API Sub Project's API Release Tracking page. |
API releases
In preparation of a public-release API the release of a public API version, an API Sub Project can create as many wip, alpha and release-candidate API versions as needed for API development and testing. The API versioning is done as described in the API versioning guidelines here: API versioning.
...
- 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 -release API version and may be part of a meta-release
...
Public releases can have an initial or a 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.
| Info |
|---|
Initial public - releases can be
|
...
When planning to deliver a public - release API version into a meta-release, the API Sub Project needs to participate in the meta-release cycleprocess as described here: Meta-release Process.
...
- the expected alpha, release-candidate and public -release API versions need to be (pre-)released
- minimally an initial public - release need 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 name rx.y
API release numbering
API release numbers are GitHub tags of the format "rx.y".
...
- 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 through 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 its the API release typesprocess.
| release name | API version | release number (tag) | release package | release package tag |
|---|---|---|---|---|
| N/A | work-in-progress | N/A | N/A | N/A |
| alpha release | alpha | rx.1 ... rx.m | optional | optional [ "pre-release" ] |
| release candidate | release-candidate | rx.m+1 ... rx.n | mandatory | "pre-release" |
| public |
| release | public | rx.n+1 | mandatory | "latest" |
| maintenance |
| release | public | rx.n+2 ... rx.n+p | mandatory | "latest" |
How to create an API release ?
An API release is created using the GitHub PR and release features and 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.
...
This section gives the overview of the steps to release an API. More details can be found in the API Release Process description.
- 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: API release tracking process.
- 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
- Once the required stability is reached, create the "release PR" (see details below in the section Create the release PR)
- 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 same as the next release tag 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 name shall be referred to by the API name (for definition see the section on on API versioning) followed by the release number e.g. qod quality-on-demand rx.y
- Repeat step 3, 4 and 5 for
- alpha releases up to M3 (for an API, the first release - candidate is created for M3)
- release - candidates between M3 and M4
- the public-release public release for M4
In case that an update of to a public -release API version x.y.z is required, the patched public -release API version x.y.z+1 shall be created through a maintenance - release on a separate branch referred to as a maintenance branch.
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).
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 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 having doing a release)
- the update of the <API name>-API-Readiness-Checklist.md which confirms the availability of all required release assets as defined 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)
- the update of the version information in the API OAS definition files file(s) 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 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 final release-candidate versions version of the APIsAPI.
Merge the release PR and create the GitHub 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 tick the "Set as a pre-release" , box; for public -or maintenance releases, tick "Set as latest release".
Maintain a public release
...
Example steps for a MINOR update change of a public -release API version 1.0.0, resulting in a new public-release 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 "release PR" that sets the API version to 1.1.0-alpha.1.
- Several alpha API versions may be released, each setting the API version back to "wip" during the first API update PR.
- Then (at least) one (or more) release-candidate API versions may be created and released.
- The last release-candidate API version will be proposed for meta-public release.
- For meta-release approval, create the "release PR" for the next public -release API version 1.1.0.
- After meta-release approval, create the release for the new public -release API version 1.1.0, with its release tag rx+1.n and release package ("latest")).
The release of a PATCH CHANGEA PATCH change to a public release rx.y is done using a dedicated maintenance branch which . This allows for a shorter release cycle process as follows:
- A dedicated maintenance branch shall be opened for the PATCH of the API
- the branch name shall be maintenance-rx.y where rx.y is the release number of the first public-release of the API being patched
- Subsequent patches shall be done on the same maintance branch
- The changes are proposed as usual through Issues and Pull Request (PRs) , PRs, and commits to this maintenance branch (using wip version)
- The final API update results in After all changes are done, a maintenance - release is created with the new public -release API version x.y.z+1 (per semver 2.0.0) and release number rx.y+1.
This maintenance - release of the patched public -release API version replaces the existing public -release API version in the meta-release. The API tracker shall be updated with the new release tag link.
The PATCH delivered through a the 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 -release API version x.y.z+1 (incrementing z) as long as needed.
...
The template for the checklist is the the API-Readiness-Checklist.md file located in the Release Management ReleaseManagement / documentation repository (link tbd).
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. qodquality-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 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 release 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
- 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 release may not yet provide all mandatory release assets for the release type.
- 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.
Explanations
The following table explains each of the release assets expected to be delivered in the API release.
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 refers to the guidelines in the API-Design-Guidelines.md document. A subset of these design guidelines have been mapped to corresponding linting rules provided by Commonalities, that can be executed against the OAS API definition file if linting is enabled for the Sub Project. For the design guidelines that cannot (yet) be verified by linting rules, the API Sub Project team shall ensure coverage manually. Ideally, a checklist of such guidelines would be provided by the Commonalities team. In particular, API Sub Project shall verify data type alignment to the Commonalities/artifacts/CAMARA_common.yaml |
3 | Guidelines from ICM applied | This refers to the guidelines described in the documents available in the IdentityAndConsentManagement / documents folder 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 shall be covered manually by the API Sub project team. Ideally, a checklist of such guidelines would be provided 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. API versioning is described in the API-Design-Guidelines.md document. |
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. Please note that User Stories shall be provided when an API is first submitted to the CAMARA API backlog. |
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 and main error cases (of course you may provide more if available). Details can be found in the API Testing Guidelines (in Commonalities GitHub). Basic tests are sufficient for an initial public-release. |
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. Details can be found in the API Testing Guidelines (in Commonalities GitHub). Enhanced tests are required for a stable public-release. |
9 | Test result statement | A statement in a discussion issue of the 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. The API release numbering is described here: |
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 public - release was certified | The previous 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 market launch and certification page. |
...
Note 2: the addition of a Security review release asset beyond the Commonalities linting rules is for further study.
Checklist per API version type
...
- its version type: alpha, release-candidate or public-release
- for public -release types, versions, in addition, depending on its target status: initial or stable
...
Nr | API release assets | alpha release | release - candidate | public- initial public releaseinitial | stable public -release stablerelease | Status | Comments |
1 | API definition | M | M | M | M | link | |
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 | link | |
6 | Basic API test cases & documentation | O | M | M | M | link | |
7 | Enhanced API test cases & documentation | O | O | O | M |
| link |
8 | Test result statement | O | O | O | M | link | |
9 | API release numbering convention applied | M | M | M | M | ||
10 | Change log updated | M | M | M | M | link | |
11 | Previous public-release was certified | O | O | O | M |
API pre-releases
To prepare the release of 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 releasescandidates, input to subsequent public - release.
Additional pre-releases can be created by an API Sub Project as they see fit.
...
- 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 release 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.
...
- 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.
...
| Info | ||
|---|---|---|
| ||
API pre-releases (alpha release 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 The release of a public API version is created when the final release-candidate API version is approved for a meta-release.
- Before M4, the release PR 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 of an API version is introduced if/when there are updates to the API (major/minor/patch).
...
- Before M4, the API Sub Project shall announce their readiness for public - release of an API version by adding the release 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 release PR for 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
...
API
An update of a public -release API version 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 widely announced and discussed with API consumers.
...
Breaking (major) or non-breaking (minor functional) updates to a public -release API version, shall result in a new release version 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 following the meta-API release cycle milestonesprocess.
- The next release numbering starts at rx+1.1 with respect to the previous public - release rx.y.
- The updated API version 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 publicly released API is prepared on a dedicated maintenance branch. This branch will continue to exist until its updates are integrated into the main branchMAJOR version is deprecated.
- The patch "release PR" will create a new public -release API version (vx.y.z+1) which can be released immediately without waiting for the next replaces the previous public release in the latest 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 maintenance - release replaces the public -release API version in the existing meta-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 The API Sub Project must not contain any API with a wip version within a 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.
...