FOR REVIEW
The Release Management process targets the creation of public-releases of APIs, aligned with the Commonalities and ICM release in a given meta-release.
In the meta-release cycle, the API release process describes how to prepare the public-release of an API version.
IMPORTANT
API release numbers are decoupled from API version numbers.
API releases are just numbered sequentially, while API versions follow the API versioning guidelines.
The following sections describe how to plan an API release and how to report progress on it.
What is an API release ?
In preparation of a public-release API version, an API Sub-project can create many wip, alpha and release-candidate API versions during the API development. The API versioning is done as described in the API versioning guidelines here: API versioning.
It is up to the API Sub-project to decide if/when to create a pre-release for an alpha or release-candidate API version.
When planning to deliver a public-release API version into a meta-release, certain pre-releases are expected to be made available during the meta-release cycle, along with the related set of release assets. The expected and optional pre-releases are described below.
Definitions
| Term | Definition |
|---|---|
pre-release | The term pre-release can be used to refer to any of the alpha or release-candidate releases of an API version. NOTE: all pre-release API versions 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 | The term release can be used to refer to either a pre-release or a public-release of an API version. |
meta-release | A meta-release is a set of public-release API versions made available at a given point in time (Spring and Fall). All API versions of a given meta-release shall be aligned to the Commonalities and Identity and Consent Management releases included in that same meta-release. |
release tag | A release tag is a GitHub tag placed on the main or a maintenance branch to allow locating the corresponding API version in the repository. |
| release package | A release package is a zip file created using the GitHub release mechanism together with the release tag. It contains a snapshot of the API Sub-project repository with the content indicated by the release tag. |
How to create an API release ?
An API release is created using the GitHub release feature and results in:
- a release tag (following the release numbering guidelines below) on the main or on a maintenance release branch, identifying the set of release assets for the API version to be released.
- a release package containing the corresponding API release assets for the released API version (zip file).
API releases are numbered following the API release numbering guideline (see below).
API release numbering
API release numbers are GitHub tags of the format "rx.y".
The release numbers shall follow the guidelines described below.
- Release numbers start with x=0 and y=1: r0.1.
- y is incremented by 1 at each subsequent alpha, release-candidate and public release, and for a maintenance release, e.g. rx.y+1.
- After a meta-release of an API through release rx.y, the next release number for this API is rx+1.0 (y resets to 0).
- In case of maintenance of a release rx.y, the new release shall be rx.y+1.
Example of continuous release numbering across the API version.
| API version | release tag | release package | release package tag |
|---|---|---|---|
| work-in-progress | N/A | N/A | N/A |
| alpha | rx.1 ... rx.m | optional (exception: mandatory for M3 milestone) | optional [ "pre-release" ] |
| release-candidate | rx.m+1 ... rx.n | mandatory | "pre-release" |
| public-release | rx.n+1 | mandatory | "latest" |
For an API released with rx.y, when preparing the next meta-release, the release numbering starts at rx+1.0.
API release checklist
NOTE: It is proposed that the checklist is moved here and referenced from the Commonalities project. Also the checklist is copied onto the release mgmt page. Alternatively, it can be provided as a file in GitHub to be copied in each API Sub-project.
An API version for which a release is created needs to provide the related set of release assets.
The following table explains each of the release assets expected to be delivered.
Nr | API release assets | Explanation |
1 | API definition | This is the OAS API definition file (yaml/json per https://spec.openapis.org/oas/v3.0.3). 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 followed | This corresponds to a set of linting rules provided by Commonalities that are successfully executed against the OAS API definition file. The output report of the linting shall be provided. Other guidelines that cannot be verified by linting rules should be listed by the Commonalities team |
3 | Profile guidelines from ICM followed | This corresponds to a set of linting rules provided by ICM that are successfully executed against the OAS API definition file. The output report of the linting shall be provided. |
| 4 | API versioning conventions followed | 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. The current camara_info_version_format rule needs to be created/updated. |
| 5 | Linting rules enabled | The linting rules provided by Commonalities that are successfully executed against the OAS API definition file. The output report of the linting shall be provided. |
6 | API documentation | The API specification should include all the needed documentation. API documentation beyond the 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 |
7 | User stories | At least 2 User Stories need to be documented by the API Sub-project team and validated by the CAMARA User Council. User Stories shall follow the provided template: Userstory-template.md and be located in the home/documentation/API_documentation folder of the API Sub-project. |
8 | Sunny day API test cases and 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. |
9 | Full set of API test cases and 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 |
10 | Test results (API test cases passed) | All available Gherkin feature files have been successfully executed against an (which?) API implementation and the test result report is provided. |
11 | Security review | API definition shall include a security scheme section that complies with the AuthN&AuthZ techniques agreed in Commonalities. Can a linting rule be provided ? |
12 | Maintainers (from at least 3 distinct companies) | This needs to be checked and confirmed by the API Sub-project team in the API Sub-project home/MAINTAINERS.md file. |
13 | Codeowners (from at least 3 distinct companies) | This needs to be checked and confirmed by the API Sub-project team in the API Sub-project home/CODEOWNERS file. |
14a | API release numbering conventions followed | This is verified using the information on the release tracker page. |
14b | Release notes according to template | Release notes need to be provided following the template and are located in the . |
| 15 | Protected branches enabled | Do we still need this ? As there are no more release publication branches, this would only apply to maintenance release branches ? |
16 | Release-candidate API version tested in at least 2 operator implementations | References to at least 2 operator implementations of the API are provided. In which form shall this information be provided ? Links to websites could be added to the API release tracker. |
17 | initial public-release API version certified and launched in at least 2 operators is needed to become stable | References to at least 2 certifications and at least 2 commercial operator implementations of the API are provided. In which form shall this information be provided ? Links to websites could be added to the API release tracker. |
The following table is the checklist of the assets that need to be provided for the release of an given API version.
Nr | API release assets | alpha | release-candidate | public-release | |
initial | stable | ||||
1 | API definition | Y | Y | Y | Y |
2 | Design guidelines from Commonalities followed | N | Y | Y | Y |
3 | Profile guidelines from ICM followed | N | Y | Y | Y |
| 4 | API versioning conventions followed | Y | Y | Y | Y |
| 5 | Linting rules enabled | Y | Y | Y | Y |
6 | API documentation | Y | Y | Y | Y |
7 | User stories | Y | Y | Y | Y |
8 | Sunny day API test cases and documentation | N | Y | Y | Y |
9 | Full set of API test cases and documentation | N | N | Y | Y |
10 | Test results (API test cases passed) | N | Y | Y | Y |
11 | Security review | Y | Y | Y | Y |
12 | Maintainers doc (from at least 3 distinct companies) | Y | Y | Y | Y |
13 | Codeowners doc (from at least 3 distinct companies) | Y | Y | Y | Y |
14a | API release numbering conventions followed | Y | Y | Y | Y |
14b | Release notes according to template | Y | Y | Y | Y |
| 15 | Protected branches enabled | Y | Y | Y | Y |
16 | Release-candidate API version tested in at least 2 operator implementations | N | N | Y | Y |
17 | initial public-release API version certified and launched in at least 2 operators is needed to become stable | N | N | N | Y |
To be part of a meta-release, minimally the initial release assets need to be provided.
API pre-releases
To prepare the public-release API version, at least two intermediate API versions must be (pre-)released as follows:
- M3: the final alpha API version implementing the defined API scope for the release, agreed stable for functional testing and aligned to the Commonalities and ICM M1 release.
- M4: the final release-candidate API version ready for meta-release approval, aligned to the Commonalities and ICM M2 release
Additional pre-releases can be created by an API Sub-project as they see fit.
pre-release of an alpha API version
- To create a pre-release of an alpha API version, the corresponding release tag and, optionally, the release package shall provide all relevant alpha assets of the API release checklist.
- An alpha API version cannot be proposed for meta-release. It first needs to go to a release-candidate API version.
pre-release of a release-candidate API version
- To create a pre-release of a release-candidate API version, the corresponding release tag and the release package shall provide all relevant rc assets of the API release checklist.
- When a release-candidate API version is proposed for meta-release, the public-release API version PR needs to be prepared.
- This public-release API version PR needs to go through TSC approval in order for the API version to be included in the meta-release.
IMPORTANT
API pre-releases (alpha or release-candidate) available in the CAMARA GitHub can be freely used, BUT AT THE USER'S OWN RISK.
API public-release
A public-release API version is created when the final release-candidate API version is approved for a meta-release.
- M5: the release with the public-release API version and all public-release assets are created in line with the target maturity status of the API version.
- Inclusion in the meta release is done by updating the API release tracker with the date and tag of this release.
A next public-release API version is introduced if there are updates to the API (major/minor/patch).
API meta-release
To be approved for meta release
- The API Sub-project shall announce their readiness for public-release of an API version by adding the PR for the public-release API version on their API release tracker page.
- After check by the Release Management team, approval of the PR is requested to the TSC.
- The TSC shall document their approval on the API release tracker.
- Once approved, the API Sub-project shall commit the public-release API version PR, create the release tag and release packages
- Finally the API Sub-project shall update the API release tracker accordingly.
Updating a public-release API
An update of a public-release 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 shall be widely announced and discussed with API consumers.
Releasing breaking or non-breaking updates
Breaking (major) or non-breaking (minor functional) updates to a public-release API, shall result in a new release of that API in the next meta-release.
- The development of the update(s) is done against the main branch.
- The same pre-release and public release steps apply at the meta-release cycle milestones.
- The release numbering starts at rx+1.1 with respect to the previous public-release rx.y.
- The updated API shall be released in the next meta-release, following the normal API release process.
Example for a non-breaking update of a public-release API version 1.0.0, resulting in a new release with API version 1.1.0:
- Develop the 1.1.0 update on the main branch
- Once sufficiently stable, create release rx+1.1 for API version 1.1.0-alpha.1
- Create pre-releases for additional alpha API versions as needed, with or without release packages
- Create pre-releases for one or more release-candidate API versions (release tag + release package)
- Based on the last release-candidate API version and its release assets, the PR for the new public-release API version shall be proposed for meta-release.
- After meta-release approval, create the public release for the new public-release API version 1.1.0, with its release tag rx+1.n and release package ("latest")).
Maintenance release
Once an API has been published as part of a meta-release, situations may occur where minor or patch changes to this API need to be made, without necessarily waiting for the next meta-release.
- The patch update is prepared on a dedicated maintenance branch which needs to be created for the maintenance of the API.
- The changes are proposed through Pull Request (PRs) and committed to the maintenance branch.
- The version of the resulting updated API shall follow the semver rules for minor/patch.
- A new public-release may be created immediately without waiting for the next meta-release.
- The release number in case of maintenance of a release rx.y, shall be rx.y+1
- The availability of the new release should be reflected through the API release tracker page.
- A patch release replaces the released API version in the existing meta-release.
Multiple APIs in one release
Although it is highly recommended to develop each API in its own API Sub-project, an API Sub-project may contain multiple APIs, which will result in release multiple APIs in one release. For this case, a public-release can only be created if each contained API provides the required set of public-release assets.
In all cases, each API shall have its own release tracker page, and, in this case, the same release tag will appear in multiple API release trackers.