API Release Process

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.

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

• released outside the meta-release process in order to allow for rapid evolution.

• released as part of a meta-release, after which it is expected that in the next meta-release this API version becomes stable.

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 in the API'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 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. For each API version planned for public release (as part of or outside a meta-release), its release tracker shall be created under their API Release Tracking page on the CAMARA Wiki.

N/A

work-in-progress

N/A

N/A

N/A

pre-release

alpha

rx.1 ... rx.m

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"

Nr

API release assets

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_definitionfolders of the API repository and validated using the linting rules in point 2. 

2

Design guidelines from Commonalities applied

This references the applicable release of the guidelines from the Commonalities repository, in particular the CAMARA-API-Design-Guide.md, and the CAMARA-API-Event-Subscription-and-Notification-Guide.md. See also the example in Commonalities / artefacts / camara-cloudevents / event-subscription-template.yaml.

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 or independent Sandbox shall ensure coverage manually. Ideally, a checklist of such guidelines would be provided by the Commonalities team.  In particular, the API Sub Project or independent Sandbox team 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 or independent Sandbox 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 repository.

6

User Stories

User Stories need to be documented by the API Sub Project or independent Sandbox 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 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 or independent Sandbox team.

9

Test result statement

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 or independent Sandbox members that the Gherkin feature files have been successfully executed against their (lab) API implementation. 

Example: Test statements for stable APIs quality-on-demand and qos-profiles v1.0.0 · Issue #418 · camaraproject/QualityOnDemand

10

API release numbering conventions applied

This is verified using the information on the API release tracker. 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 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.

13

API description (for marketing)

This is the link to the API description used for marketing the API. The API description is a Wiki page located under the home Wiki page of the API repository created from the api-description template (to be defined). Please see here for an example API description.

Nr

API release assets

1

API definition

2

Design guidelines from Commonalities applied

3

Guidelines from ICM applied

4

API versioning convention applied

5

API documentation

6

User Stories

7

Basic API test cases & documentation

8

Enhanced API test cases & documentation

9

Test result statement

10

API release numbering convention applied

11

Change log updated

12

Previous public release was certified