FOR REVIEW
The API Release Management process targets Process describes the creation of public(pre-)releases of API versions , aligned with the Commonalities and ICM release in throughout the API lifecycle, and for a given meta-release.
In the For a meta-release cycle, this API release process describes how to prepare the public-release of an API versionthe API Release Process targets the release of public API versions, aligned with the corresponding Commonalities and ICM public versions.
| Info | ||
|---|---|---|
| ||
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 create an API release and how to report progress on it during the meta-release cycleprocess.
| Table of Contents |
|---|
Definitions
| Term | Definition |
|---|---|
pre-release |
A pre-release is a GitHub release of |
pre-release
The term pre-release is used to refer to the release of any of the alpha or release-candidate API versions.
NOTE: allan 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 |
All API versions of a given meta-release shall be aligned to the Commonalities and Identity and Consent Management public-releases included in that same meta-release.
release tag
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.
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). This is optional for intermediate alpha releases.
API releases are numbered (tagged) following the API release numbering guideline (see below).
How to create an API release ?
To create an API release, a "release PR" (and the associated PR issue) needs to be created to do a release of the API's repository:
- The “release PR” does not change the content of what is in the repository (either an alpha release, a release-candidate or a public-release API version)
- The “release PR” provides (only) the following changes:
- No API in the repository shall have “wip” within the version in the API OAS definition file
- The version of at least one API will be changed (otherwise there is no sense in having a release) as follows:
- only the delta to the previous release for an alpha API version
- for the first release-candidate, all changes since the last public-release
- for the subsequent release-candidate, only the delta to the previous one
- for the public-release, the consolidated changes since the last public-release
- the version information in the API OAS definition files within the repository
- the update of the <API name>-API-Readiness-Checklist.md which confirms the availability of all required release assets as defined for the release type: API Release Process
- the update of the Changelog.md in the repository
- the update of the README.md (if necessary)
- A “release PR” has to be approved before the code owner is allowed to merge as follows:
- alpha releases: by one other code owner (as for any PR)
- release-candidates: by the majority of the sub project Maintainers + one Release Manager
- public-releases:
- by the majority of the 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)
- NOTE: public-release should have a formal approval, the actual review is done based on the release-candidate versions of the APIs.
It is expected that only one or two release-candidates will exist for an API.
API release numbering
API release numbers are GitHub tags of the format "rx.y".
IMPORTANT: Release numbers are not related to the API version.
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 public-release shall be rx.y+1.
Example of continuous release numbering across the API version.
...
release tag
...
release package
...
rx.1 ... rx.m
...
optional (exception: mandatory for M3 milestone)
...
rx.m+1 ... rx.n
...
For an API released with rx.y, when preparing the next meta-release, the release numbering starts at rx+1.0.
API readiness checklist
NOTE: The API readiness checklist .md file which can be copied for API sub-projects will be provided in the Release Management repository (link tbd).
An API version for which a release is created needs to provide the related set of release assets.
- The availability of the release assets needs to be recorded in the API readiness checklist .md file(s) in the API Sub-project repository.
- There needs to be one API readiness checklist per API, updated for each API version.
- There is a different API readiness checklist for Sandbox API Sub-projects than for Incubated API Sub-projects.
Sandbox API readiness checklist
The following table explains each of the release assets expected to be delivered as part of an API release for a Sandbox API Sub-project.
Incubated API readiness checklist
The following table explains each of the release assets expected to be delivered as part of an API release for an incubated API Sub-project.
...
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 applied
...
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, in particular data type alignment to the Commonalities/artifacts/CAMARA_common.yaml
...
3
...
Profile guidelines from ICM applied
...
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.
...
API versioning conventions 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. The current camara_info_version_format rule needs to be created/updated.
...
5
...
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
...
6
...
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.
...
7
...
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.
...
8
...
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
...
9
...
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.
...
10
...
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 ?
...
11
...
API release numbering conventions applied
...
This is verified using the information on the release tracker page.
...
12
...
Release notes according to template
...
Release notes need to be provided following the template and are located in the .
...
13
...
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.
...
14
...
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 API readiness 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 applied
...
N
...
Y
...
Y
...
Y
...
3
...
Profile guidelines from ICM applied
...
N
...
Y
...
Y
...
Y
...
API versioning conventions applied
...
Y
...
Y
...
Y
...
Y
...
5
...
API documentation
...
Y
...
Y
...
Y
...
Y
...
6
...
User stories
...
Y
...
Y
...
Y
...
Y
...
7
...
Sunny day API test cases and documentation
...
N
...
Y
...
Y
...
Y
...
8
...
Full set of API test cases and documentation
...
N
...
N
...
Y
...
Y
...
9
...
Test results (API test cases passed)
...
N
...
Y
...
Y
...
Y
...
10
...
Security review
...
Y
...
Y
...
Y
...
Y
...
11
...
API release numbering conventions applied
...
Y
...
Y
...
Y
...
Y
...
12
...
Release notes according to template
...
Y
...
Y
...
Y
...
Y
...
13
...
Release-candidate API version tested in at least 2 operator implementations
...
N
...
N
...
Y
...
Y
...
14
...
initial public-release API version certified and launched in at least 2 operators is needed to become stable
...
N
...
N
...
N
...
Y
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 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. 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. |
API releases - overview
To prepare the release of a public API version, API versions shall be (pre-)released as follows:
- before M3, release one or more alpha API versions as needed
- to reach M3, release the first release-candidate API version:
- 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 API Sub Project can release as many alpha and release-candidate API versions as useful for API development and testing. 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. |
Public API versions
Public API versions can have an initial or a stable status.
| Info |
|---|
Please note that initial public API versions can be
|
A public 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.
Meta-release
To be part of a meta-release, the API Sub Project needs to participate in the meta-release process. For the meta-release, the following needs to be provided:
- the API release tracker (see [API release trackers](https://wiki.camaraproject.org/x/HQBFAQ))
- the expected (pre-)releases at the respective M3 and M4 milestones
- minimally an initial public API version
- the required set of API release assets according to the API readiness checklist (see below).
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:
- Develop the 1.1.0 updates on the main branch. The first PR shall update the OAS file setting the API version to wip, and the URL to vwip.
- Once sufficiently stable, create a release PR for the API version 1.1.0-alpha.1.
- After release PR approval, create the pre-release rx.1 and publish it on the API release tracker.
- Several alpha API versions 1.1.0-alpha.p may be released, each setting the API version back to "wip" in the first API update PR and evolving the alpha number with each following pre-release (rx.2 - rx.m).
- When the API version is ready, create a release PR for the API version 1.1.0-rc.1
- Several release-candidate API versions 1.1.0-rc.q may be released, each setting the API version back to "wip" in the first API update PR and evolving the rc number with each following pre-release (rx.m+1 - rx.n).
- When the API version is ready for public release, create the release PR that sets the public API version to 1.1.0. (this PR minimally removes the rc extensions from the version and URL fields in the API yaml file and assures all API release assets are available as per the API readiness checklist).
- After release PR approval, create the release rx.n+1 and publish it on the API release tracker.
- The approved public API version 1.1.0 will be included in the meta-release as planned.
API release numbering
API release numbers are GitHub tags of the format "rx.y".
| Info |
|---|
| IMPORTANT: Release numbers are not related to the API version. |
The release numbers shall follow the guidelines described below.
- 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 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 following table illustrates the continuous release numbering of an API version across the API release process.
| 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" |
API readiness checklist
To release an API version, an API Sub Project needs to provide the required release assets as specified in the API Readiness Checklist (see description below).
The template for the checklist is the API-Readiness-Checklist.md file located in the CAMARA / ReleaseManagement / documentation repository.
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/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 a release-candidate and the checklist of a subsequent public API version may be 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 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: Userstory-template.md and be located in the home/documentation/API_documentation folder of the API Sub Project.
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
In the table,
- "M" indicates a mandatory release asset
- "O" indicates an optional release asset which may be provided with the release, if available.
The API-Readiness_Checklist.md is available in GitHub for copying to the API Sub projects.
Nr | API release assets | alpha | release- candidate | initial public (v0.y.z) | stable public (vx.y.z, x>=1) | Status | Comments |
1 | API definition | M | M | M | M | link | |
2 | Design guidelines from Commonalities applied | O | M | M | M | ||
3 | Guidelines from ICM applied | O | M | M | M | ||
| 4 | API versioning convention applied | M | M | M | M | ||
5 | API documentation | M | M | M | M | link | |
6 | User Stories | O | O | O | M | link | |
7 | Basic API test cases & documentation | O | M | M | M | link | |
8 | Enhanced API test cases & documentation | O | O | O | M | link | |
9 | Test result statement | O | O | O | M | link | |
10 | API release numbering convention applied | M | M | M | M | ||
11 | Change log updated | M | M | M | M | link | |
12 | Previous public-release was certified | O | O | O | M |
API releases - details
The GitHub release feature
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.
A GitHub release is the combination of a release tag and, optionally, a release package created using the GitHub release feature for an API repository. A GitHub release may not contain any wip APIs versions.
Releasing an API step by step
This section gives the overview of the steps to release a public version of an API.
- 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
- To reach M3, a release PR 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 of one or more release-candidate API versions may be created between M3 and M4
- To reach M4, a release PR 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.
- To release the API, manage the release PR approval, merge the approved release PR and create the release (see below).
NOTE: To be included in the meta-release, the release of the public API version needs to be available.
Prepare the API release
To create a (pre-)release of the API, a release PR (linked to the associated release scope issue) must be created.
A release PR does not change the content the repository other than the following changes:
- 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 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 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 as reviews in the release PR in GitHub.
Merge the release PR and create the GitHub release
Once approval is obtained, merge the release PR and create the GitHub release:
- The GitHub release package is (optionally) created using the GitHub release feature.
- The release tag shall be named with the next release number and shall have the following format: rx.y
- The x.y number shall follow the release numbering scheme as defined in the above section on Release Numbering.
- Note: Outside the project, the release shall be referred to by the API repository name (for definition see the section on API versioning) followed by the release number e.g. quality-on-demand rx.y
- The release description shall be copied from the CHANGELOG.md (as described above)
- For releases with alpha and release-candidate API versions, tick the "Set as a pre-release" box; for public or maintenance releases, tick "Set as latest release".
Track the release
- Update the API release tracker with the date and tag of the (pre-)release to show progress.
Maintain a public release
An update of a publicly released
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.
| Info | ||
|---|---|---|
| ||
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. Such updates shall be widely announced and discussed with API consumers.
...
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
Breaking (majorMAJOR) or non-breaking (minor functionalMINOR ) updates to a public -release API version, shall result in a new release version 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.
...
For the release of a MAJOR or MINOR update of a publicly released API, the normal API release process (as described above) is applied.
For a MAJOR or MINOR update to a public release rx.y, the next public released is rx+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 rx.y, the next released is rx.y+1. The new public API version will be vx.y.z+1
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)
- 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 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 -projectProject, an API Sub -project Project may contain multiple, closely related APIs, which . Because a release concerns the whole API repository, this will result in release releasing multiple APIs in one release. For In this case, a public-release an API version can only be created released if each all contained API provides 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 (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.
...