The API Release Process describes the creation of (pre-)releases of API versions throughout the API lifecycle, and for a given meta-release.
...
release type | API version | release number (release tag) | release package | release package label |
|---|---|---|---|---|
N/A | work-in-progress | N/A | N/A | N/A |
pre-release | alpha | rx.1 ... rx.m | optional | optional: "pre-release" |
pre-release | release-candidate | rx.m+1 ... rx.n | mandatory | "pre-release" |
release | public | rx.n+1 | mandatory | "latest" |
maintenance release | public | rx.n+2 ... rx.n+p | mandatory | "latest" |
...
The template for the checklist is the API-Readiness-Checklist.md file located in the CAMARA / ReleaseManagement / documentation repository folder.
For the readiness of a given API version, an API Sub Project needs to
copy the API-Readiness-Checklist.md file(s) to the API Sub Project repository in the <home>/documentation/API_documentation folder.
rename the file to include <API name> as prefix 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
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 pre-release may not yet provide all mandatory release assets for the release type.
update the Reference Information column with the relative link to the asset in the repository (if applicable), and any other additional links or comments as needed For the point 12: you can copy the following link if your previous API version has been certified: GSMA OGW Portal(see explanations below).
NOTE: the checklists of a public API version and of its preceding release-candidate API version can be the same.
...
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 located in the code/API_definition folders of the API repository and validated using the linting rules in point 62. |
2 | Design guidelines from Commonalities applied | This references the applicable release of the guidelines from the Commonalities repository, in particular the API-design-guidelines.md. A subset of these design guidelines have been mapped to corresponding linting rules as described in Commonalities / documentation / Linting-rules.md, which shall be executed against the OAS API definition file once linting is enabled for the API repository. 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 Projects shall verify data type alignment with those in the the Commonalities / artifacts / CAMARA_common.yaml file |
3 | Guidelines from ICM applied | This references the applicable release of the guidelines from the IdentityAndConsentManagement repository, and to the related linting rules provided by ICM (provided to Commonalities) 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 Commonalities / documentation / API-design-guidelines.md document. |
5 | API documentation | The API specification shall include all the documentation needed by the API consumer. It shall include the mandatory authentication and authorization text as defined in the section on security in the API-design-guidelines.md. Any explanatory API documentation beyond the one embedded in the API definition file, shall be located in the /documentation/API_documentation folder of the API Sub Project. |
6 | User Stories | User Stories need to be documented by the API Sub Project team. It is recommended to have at least 2 different User Stories. User Stories shall follow the template found here: Commonalities / documentation / Userstory-template.md and be located in the /documentation/API_documentation folder of the API repository. Please note that User Stories shall be provided when an API is first submitted to the CAMARA API backlog / documentation / APIbacklog.md. |
7 | Basic API test cases & documentation | At least one Gherkin feature file shall be provided for the API in the /code/Test_definitions folder of the API repository covering sunny day scenarios and main error cases (of course you may provide more if available). Guidance can be found in the Commonalities / documentation / API-Testing-Guidelines.md. Basic tests are sufficient for an initial public release. |
8 | Enhanced API test cases & documentation | Gherkin feature files are shall be provided for the API in the /code/Test_definitions folder of the API repository covering sunny and rainy day scenarios. Details can be found in the Commonalities / documentation / API-Testing-Guidelines.md. Enhanced tests are required for a stable public release. NOTE: the enhanced test cases can be in the same or different test file(s) as the basic test cases. The choice is up to the API Sub Project |
9 | Test result statement | References Links to the scope issue (or any other relevant issue) for the API version that contains a statement 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 API release tracker page. The API release numbering is described here: API Release Process - section on API release numbering |
11 | Change log updated | The changelog needs to be provided following the template which can be copied from here: ReleaseManagement / documentation / CHANGELOG_TEMPLATE.md. A good example usage of the template is the the following: QualityOnDemand/CHANGELOG.md. Please refer to the more recent releases using the release numbering scheme (rx.y). |
12 | Previous public release was certified | The previous public API version had at least 1 certified implementation. The Reference to at least 1 certification of the API is provided on the GSMA API market launch and certification page. |
Note 1: User Stories are being handled when submitting an API to the API backlog (see here). It is recommended to have at least 2 user stories, which need to be documented by the API Sub Project team. User Stories shall follow the template from Commonalities / documentation / Userstory-template.md and be located in the /documentation/API_documentation folder of the API repository.
...
information section shall reference a note (e.g. "see (1)") under the checklist table to be added that states the certified company(s) as can be found on the following link: GSMA Open Gateway Portal. |
Note: the addition of a Security review release asset beyond the Commonalities linting rules is for further study.
Readiness checklist per API version
...
Nr | API release assets | alpha | release- candidate | initial public (v0.y.z) | stable public (vx.y.z, x>=1) | Status | Reference information | |
1 | API definition | M | M | M | M | relative link: /code/API_definitions/apiname.yaml | ||
2 | Design guidelines from Commonalities applied | O | M | M | M | Comm. release nr | ||
3 | Guidelines from ICM applied | O | M | M | M | ICM release nr | ||
4 | API versioning convention applied | M | M | M | M | x.y.z | ||
5 | API documentation | M | M | M | M | relative link: /documentation/API_documentation/apiname-API-Readiness-Checklist.md | ||
6 | User Stories | O | O | O | M | relative link: /documentation/API_documentation/apiname-Userstory.md | ||
7 | Basic API test cases & documentation | O | M | M | M | relative link: /code/Test_definitions | ||
8 | Enhanced API test cases & documentation | O | O | O | M | relative link: /code/Test_definitions | ||
9 | Test result statement | O | O | O | M | issue link | ||
10 | API release numbering convention applied | M | M | M | M | rx.y | ||
11 | Change log updated | M | M | M | M | relative link: | ||
12 | Previous public release was certified | O | O | O | M | linkcomment |
Explanations on the above table
The Status column shall contain "Y" (yes) if the release asset is available or fulfilled in the current release, or "N" (no) or "tbd". Example use of "tbd" is in case an alpha or release-candidate API version does not yet provide all mandatory assets for the release.
The Reference information column, provide the links to the release asset once available, the applicable release numbers (not versions) of Commonalities and ICM, and any other relevant links or information.
For the point 12: you can put a reference to a comment that you write under the table with the involved companies and copy the following link if your previous public API version has been certified:: GSMA OGW Portal.
Note: the checklists of a public API version and of its preceding release-candidate API version can be the same.
...
Technically, an API (pre-)release is created using the GitHub release feature (see Draft/publish a new release). It involves
A GitHub issue defining the scope of the target API version.
A release PR associated to this issue.
After release PR approval:
a release tag (with the tag name following the API release numbering guidelines above) on the main or on a maintenance release branch.
a release package containing the API's repository with the corresponding API release assets for each contained API version (zip file). A release package is optional for pre-releases of alpha API versions.
...
the update of the version information in the API OAS definition file(s) within the repository (Info/version field and URL version)
no API in the repository shall contain “wip” in the version field in the API OAS definition file
at least the version of one API must be changed with respect to the previous release (otherwise there is no sense in doing a release)
the update of all links (URLSURLs) to point to resources in the release and hence include the release number on their path (no links with "main", no relative links).
the update of the API-Readiness-Checklist.md for each API in the repository which confirms the availability of all release assets required for the (pre-)release. For details, see the explanations on the API readiness checklist above.
the update of the Changelog.md in the repository with new content on all APIs at the top for the most recent (pre-)release as follows:
for an alpha release, the delta with respect to the previous release
for the first release-candidate, all changes since the last public release
for subsequent release-candidate(s), only the delta to the previous release-candidate
for a public release, the consolidated changes since the previous public release
the update of the README.md (as necessary)
...
Update the API release tracker with the date and tag of the (pre-)release to show progress.
...
Updating a public release
An update of a publicly 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. Such updates shall be widely announced and discussed with API consumers.
To update a public API, a next public release of this API needs to be created including the (MAJOR/MINOR/PATCH) update(s).
MAJOR or MINOR updates shall be handled through the API release process as described above
PATCH updates can be done at any time after the public API release, and as long as the API is not retired. However, once there is a stable API version, one would preferably push for adoption of the stable API, rather than patching previous initial API versions.
MAJOR or MINOR updates
Breaking (MAJOR) or non-breaking (MINOR ) updates to a public API version shall result in a new version of that API in the next meta-release. For the release of .
To release a MAJOR or MINOR update of a publicly released API, the normal API release process (as described above) is applied, including the creation of a dedicate API release tracker for this new API version.
For a MAJOR or MINOR update to a public release rxrm.yn, the next public released is rxrm+1.n.
PATCH update
A PATCH to a public release is done using a dedicated maintenance branch.
For a PATCH update to a public release rxrm.yn, the next released is rxrm.yn+1. The new public API version will be vx.y.z+1
...
A dedicated maintenance branch shall be opened to develop the PATCH of the API
the branch name shall be maintenance-rx rm where x m is the release first number of the public release rxrm.y n being patched
Subsequent patches shall be done on the same maintenance branch, and will increase the y n number in rm.n.
The changes are proposed as usual through Issues, PRs, and commits to this maintenance branch (using wip version)
It is assumed that no intermediate pre-releases are created, however, if needed for the development of the patch; this can be done and should also be tracked on the existing API release tracker.
After all changes are done, a release PR for the patched public API version shall be created. In this release PR, the API version shall be set to x.y.z+1 (per semver 2.0.0) and maintenance release number rxrm.yn+1 shall be referenced.After approval, the maintenance release is created for the new public API version used. In this release PR, already all occurrences of the API version shall use x.y.z+1 (per semver 2.0.0and links shall use the new release number rm.n+1.
After approval by the release management team, the maintenance release is created for the new public API version x.y.z+1 (per semver 2.0.0) with release number rxrm.yn+1.
This maintenance release replaces the existing public release of the API in the meta-release.The
To do this update the existing API release tracker as follows:
update the (page) title of
the release tracker to reflect the patch version x.y.z+1
update the API version field with the patch version x.y.z+1
do NOT update the Target version field (keep the original target version)
Optionally, add the previous public-release tag link and release date to the "Comments field"
update the Public release (Fall24: public-release tag) field with the new release tag rm.n+1.
update the Patch date (Fall24: M5 date) field with the date of the patch release
The PATCH delivered through a 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 (release rm.n+2, rm.n+3, etc.) of the public API version x.y.z+1 2,3,etc. (incrementing z) as long as needed, and be reflecting patches releases on the same API release tracker.
NOTE: a PATCH is the only case for which a separate branch is created and maintained in the API repository (as pull requests should be prepared within forks of the API repository, c.f. Governance/CONTRIBUTING.md).
Multiple APIs in one release
Although it is highly recommended to develop each API in its own API Sub Projectrepository, an API Sub Project repository may contain multiple, closely related APIs. Because a release concerns the whole API repository, this will result in releasing multiple APIs in one release. In this case, an API version can only be released if all contained APIs provide the required set of public release assets. The API release must not contain any API with a wip version.
In all cases, each API version shall have its own release tracker (on the wiki 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.
...