The API Release Process describes the creation of (pre-)releases of API versions throughout the API lifecycle, and for a given meta-release.
...
| Term | Definition |
|---|---|
pre-release | A pre-release is a GitHub release of an alpha or release-candidate API version. Note: the term release is also often used here but it should be clear from the context. NOTE: pre-releases are not meant to be included in a meta-release. 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. |
release | A release is a GitHub release of a public API version. Releases may be proposed as part of a meta-release. |
release of initial public API | Initial public API versions only exists for new APIs. It concerns public APIs versions with x = 0 (0.y.z without version extension). A public API version is called "initial" to indicate that the API version has not yet reached full maturity, but is considered stable enough to be proposed for use in applications. However, the user shall be aware that subsequent versions of this API may require code changes to their applications. Initial public API versions can be
|
release of stable public API | Stable public API versions are 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 API versions published together at a given point in time (Spring and Fall). All API versions of a given meta-release shall be aligned to the releases of the Commonalities and Identity and Consent Management (ICM) documentation included in that same meta-release. |
maintenance release | A maintenance release is the release of a patch update of a public API version. |
release tag | A release tag is a GitHub tag placed on the main or a maintenance branch that identifies a release of in the API version's repository. |
| release package | A release package is a zip file of the GitHub repository created using the GitHub release mechanism. It contains a snapshot of the full API version repository marked with the release tag. |
| GitHub release | A GitHub release is the combination of a release tag and, optionally, a release package of the GitHub repository (zip file) created using the GitHub release feature. A GitHub release applies to the full API repository. A GitHub release may containing any alpha, release-candidate or public API version(s). A GitHub release shall not include any wip API versions. |
| release PR | A release PR is created for an API version to prepare its GitHub release. A release PR shall minimally set the version fields in the API yaml file to the exact API version and establish the availability of the API release assets as per the API readiness checklist. |
| API release tracker | An API release tracker is a LF Confluence wiki page that provides the visibility on the progress of the (pre-)releases of a given API version. Each public API version planned for release by an API Sub Project shall have its release tracker under their API Sub Project's API Release Tracking page. |
...
To prepare the release of a public API version, at least two intermediate API versions must shall be (pre-)released as follows:
- at M3: the before M3, release one or more alpha API versions as needed
- to reach M3, release the first release-candidate API version implementing the defined API scope for the release (achieved through one or more alpha releases), agreed stable for :
- the release-candidate implements the scope of the target public API version.
- this pre-release is agreed as ready for API implementation and functional testing
- .
- it is aligned with
- the release-candidate versions of Commonalities and ICM (M1).
- between M3 and M4, release one or more release-candidate API versions as needed
- to reach M4, release the public API version:
- this is the version ready for inclusion in the meta-release
- (if so planned).
- the public API version is aligned with the public versions of Commonalities and ICM (M2).
An An API Sub Project can create release as many wip, alpha and release-candidate API versions as needed useful for API development and testing.
The API Sub Project 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 version.
- a release must be created for each public API version.
In between releases, the API version is set to "wip" (to indicate that this API version should not be used).
| Info | ||
|---|---|---|
| ||
Pre-releases (for alpha or release-candidate API versions) available in the CAMARA GitHub can be freely used, BUT AT THE USER'S OWN RISK. |
The release of an API version is created once its release PR is approved:
- Before M3 or M4, the API version release PR is prepared. It shall provide all release assets as per the API readiness checklist.
- Once the release PR is approved, the corresponding GitHub release is created and M3/M4 is declared.
- If planned, inclusion in the meta-release is done by updating the API release tracker with the M3/M4 date and release tag link.
A subsequent GitHub release of an API version is done if/when there are updates to the API. All updates shall be recorded in the Changelog.md file
...
Please note that initial public API versions can be
...
Public API versions
Public API versions can have an initial or a stable status.
| Info |
|---|
Please note that initial public API versions can be
|
- An API version is released only if it provides all required API readiness checklist items (see: [API Readiness Checklist](https://wiki.camaraproject.org/display/CAM/API+Release+Process#APIReleaseProcess-APIreadinesschecklist).
- Stable public API versions are 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.
When planning to deliver a public API version into a meta-release, the API Sub Project needs to participate in the meta-release process as described here: Meta-release Process.
In short, to be part of a meta-release,
...
. (Pre-)releases need to be provided as follows:
- the expected (pre-)releases need to be provided at the respective M3 and M4 milestones
- minimally an initial public API version release needs to be releasedprovided for the meta-release.
- each (pre-)release must provide include the required set of API release assets according to the API readiness checklist described (see below).
- API (pre-)releases are numbered (tagged) using the API release numbering guideline (see below).
GitHub release
Technically, a GitHub release is created using the GitHub features and requires:
- A GitHub issue defining the scope of the target API version.
- A release PR associated to this issue.
- After release PR approval: a GitHub release tag with the release number "rx.y" (see release numbering below).
- After release PR approval: Optionally (see table below), a GitHub release package (zip file of the whole API repository).
Example of the use of the API release process
To release a MINOR update of a public API version 1.0.0, resulting in the release of public API version 1.1.0:
...
- 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
- 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 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 pre-release may not yet provide all mandatory release assets for the release type.
NOTE: the checklists of the latest release-candidate and the checklist of a subsequent public API version are the same.
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.
Readiness checklist per API version
...