The API Release Process describes the creation of (pre-)releases of API versions through the API lifecycle, and for a given meta-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 shall create 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 versionsversion.
- a release must be created for each public API version.
...
| Info | ||
|---|---|---|
| ||
API pre-releases (for alpha release or release-candidate API versions) available in the CAMARA GitHub can be freely used, BUT AT THE USER'S OWN RISK. |
...
The release of a public API version is created once the final release candidate PR is approved for a meta-release.
- Before For 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.
- If the PR is approved, the API will be included in the meta-release.
- Inclusion in the meta-release is done by updating the API release tracker with the date and tag of this public the release.
A next public release of an a public API version is introduced if/when there are updates to the API (major/minor/patch).Public
| Info |
|---|
Initial public releases can |
...
- 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.
| Info |
|---|
Initial public releases can be released and published at any time (outside the meta-releasebe
|
...
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.
...
- the expected alpha, release-candidate and public API versions need to be (pre-)released
- minimally an initial public release API version needs to be providedreleased
- 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 a (pre-)release is created using the GitHub features and requiresrequire:
- A GitHub issue for the release.
- A "pre-release PR" or "release PR" associated to this issue.
- If required (see table below), a GitHub release package (zip file of the whole API
Sub Projectrepository). - 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 public API version 1.0.0, resulting in the public release of public 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 a pre-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 pre-released (rx.m+1 - rx.n)
- The last When the release-candidate API version will be proposed for public release. For meta-release approvalis ready, create the public release PR for the next public API version 1.1.0. (this PR minimally removes the -rc.n from the version fields in the API yaml file and assures all API release assets are available as per the API readiness checklist)
- For the meta-release, approval of the release PR is needed.
- 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")).
...
- 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
- 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.
- 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.
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: link tbd . |
12 | Previous public release was certified | The previous public 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.
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
...