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.
...
| 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 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 | The term public-release is used to refer to the release of a public-release API version. It can have the status initial or stable. |
maintenance-release | The term maintenance-release is used to refer to a patch update of a public-release API version. |
meta-release | A meta-release is a set of public-releases of 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 (ICM) 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 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 by an API Sub Project shall have a tracker under their API Sub Project's API Release Tracking page. |
...
- the expected alpha, release-candidates 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:
- A GitHub issue for the release
- A "release PR" for associated to this issue
- If required, 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".
...
Example of continuous release numbering across the of an API version across its release types.
| API version | release tag | release package | release package tag |
|---|---|---|---|
| work-in-progress | N/A | N/A | N/A |
| alpha | rx.1 ... rx.m | optional | optional [ "pre-release" ] |
| release-candidate | rx.m+1 ... rx.n | mandatory | "pre-release" |
| public-release-release | rx.n+1 | mandatory | "latest" |
| maintenance-release | rx.n+2 ... rx.n+1p | mandatory | "latest" |
How to create an API release ?
...
- A dedicated maintenance branch shall be opened for the PATCH of the API
- the branch name shall be maintenance-x.y.z where x.y.z is the current API version being patched
- The changes are proposed as usual through Issues and Pull Request (PRs) and commits to this maintenance branch (using wip version)
- The final API update results in a maintenance-release with the public-release API version x.y.z+1 (per semver 2.0.0)
This new public-release API version replaces the previous previously released API version in the mete-release.
The PATCH of the API for the maintenance-release will shall 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 this the public-release API version x.y.z+1 (incrementing z) as long as needed.
...
- 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. qod-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 or release-candidate release may not yet provide all mandatory release assets for the release type yet.
- 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 or release-candidate release may not yet provide all mandatory release assets for the release type yet.
- 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
...
- 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 The patch "release PR" will create a new public-release may be created API version (vx.y.z+1) which can be released 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 maintenance-release replaces the released 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. This 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 a 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.
...