The API Release Process describes the creation of (pre-)releases of API versions throughout the API lifecycle, and for a given meta-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
...
- Release numbers start with x=1 and y=1: r1.1.
- y is incremented by 1 at each subsequent (pre-)release (for alpha, release-candidate and public API versions), and for a maintenance release, e.g. rx.y+1.
- After a meta-release of an a public API version release rx.y, the next release number for this API is rx+1.1 (y resets to 1).
- In case of maintenance of a release rx.y, the next release shall be rx.y+1.
- A maintenance release replaces the previous release in the meta-release.
...
The template for the checklist is the API-Readiness-Checklist.md file located in the ReleaseManagement CAMARA / ReleaseManagement / documentation repository.
For the release 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/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
The following table is the API readiness checklist that lists the assets that need to be provided with the API version for it to be ready for its (pre-)release. The required assets depend on
- the API version type: alpha, release-candidate or public
- for public API versions, in addition, depending on its target status: initial or stable
...
- Create a GitHub issue defining the scope of the API version targeted to be released. Descriptive information in this issue can be reused in the changelog/release notes.
- Create the API release tracker for the targeted public API version as describer here: API release trackers.
- On the main branch, develop the API version scope in a "work-in-progress mode" (API version = wip and version in URL is vwip).
- several pre-releases for one or more alpha API versions may be created between M1 and M3
- For To reach M3, the pre-a release PR is created which contains needs to be created that updates the API to become the first release-candidate API version, including the relevant release assets (see details in section Create the (pre-)release PR below)
- Further pre-releases for of one or more release-candidate API versions may be created between M3 and M4
- For To reach M4, the a release PR is created which contains needs to be created that updates the API to become the first public API version, including the relevant release assets (see details in section Create the (pre-)release PR below)
- During above development (M1-M3) and test (M3-M4), make sure to create and record the required release assets according to the API-Readiness-Checklist.
- Manage the (pre-)To release the API, manage the release PR approval, merge the approved (pre-) release PR and create the release (see below).
NOTE: To be proposed for included in the meta-release, a release PR for a the release of the public API version needs to be available and approved.
...
Prepare the API release
To create a (pre-)release of the API's repository, first a "(pre-) release PR " (linked to the associated PR release scope issue) must be created.
A (pre-) release PR does not change the content of what is in the repository. Hence a (pre-)release PR provides (only) the repository other than the following changes:
- the update of the version information in the API OAS definition file(s) within the repository for a (pre-)release PR, (Info/version field and URL version)
- no API in the repository shall contain “wip” within in the version field in the API OAS definition file
- at least the version of one API will must be changed with respect to the previous release (otherwise there is no sense in doing a release)
- the update of the <API name>-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 the first alpha or release-candidate API version, all changes since the release of the previous public API version
- for subsequent alpha or release-candidate API versions, the delta with respect to the previous pre-release
- for a public API version, the consolidated changes since the release of the previous public API version
- the update of the README.md (as necessary)
Manage the
...
release PR approval
A (pre-) release PR has to be approved before the code owner is allowed to merge as follows:
- alpha API versions: by one other code owner (as for any PR)
- release-candidates: by the majority of the API Sub Project Maintainers + one Release Manager
- public API versions:
- by the majority of the API Sub Project Maintainers (normally given, if the preceding release-candidate was approved), and
- by the TSC (to be discussed how this will be done formally)
- the formal approval is based on the review of the release PR for the public API version
- Approvals shall be documented on as reviews in the API release tracker pagePR in GitHub.
Merge the
...
release PR and create the GitHub release
Once approval is obtained, merge the (pre-) release PR and create the GitHub release:
...
A shorter release process is applied as follows:
- An API tracker shall be created for teh maintenance version of the API (x.y.z+1)
- A dedicated maintenance branch shall be opened to develop the PATCH of the API
- the branch name shall be maintenance-rx.y where rx.y is the release number of the public release rx.y being patched
- Subsequent patches shall be done on the same maintenance branch, and will increase the y number
- The changes are proposed as usual through Issues, PRs, and commits to this maintenance branch (using wip version)(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 be tracked on the release tracker as usual.
- After all changes are done, a release PR for the patched public API version shall be created and approved.
- After approval, the maintenance release is created for the new public API version x.y.z+1 (per semver 2.0.0) and release number rx.y+1.
- This maintenance release replaces the existing public release of the API in the meta-release.
- The API tracker shall be updated with the new release tag link.
- 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 of the public API version x.y.z+1 (incrementing z) as long as needed.
NOTE: a PATCH is the only case for which a separate branch is created and maintained in the API Sub Project (not counting working branches).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)
...
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. 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 an API version can only be created released if all contained APIs provide the required set of public release assets. The The API Sub Project release must not contain any API with a wip version within the 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.
...