...
The Release Management process is based on API versions and their associated release assets. It uses
- initial ((api-0.y.z) or alpha (api-x.y.z-alpha.m) API versions (with version extensions) are used for CAMARA internal API development purposes
- release-candidate (api-x.y.z-rc.n) API versions (with version extensions) are used for CAMARA internal API release management purposes
- public-release API versions (api-x.y.z) are used for API versions that are part of a meta-release. These API versions only have API version number x.y.z (semver 2.0), no version extension.
- work-in-progress API version is used during the development of an the API in between pre-releases. This versions is not considered as a release and is not usable by API consumers.
- An API version release is identified by putting an API version tag on the main or on a release branch (the latter in case of changes to a public-released API).
- An API release consists in creating the related set of API version assets and delivering them in an API version release package.
- Note 1: People are free to use initial, alpha or release-candidate API versions available in the CAMARA GitHub at their own risk.
- Note 2: API families are not versioned, nor release-managed. Only API versions are release-managed.
...
During the API development and release preparation, alpha (-alpha) or release-candidate (-rc) extensions shall be used to identify intermediate stable versions of an API.
The notions of alpha and release-candidate API versions, and their related API version extensions, are INTERNAL to the CAMARA project and used only for the API development and release management process.
The API version extension is added to the "version" field of the OAS definition of an API, as well as to the URL (see below table). Its Its content must follow the here described syntax and semantics.
...
- alpha API versions: -alpha.m
- release-candidate API versions: -rc.n
- no extension - this is allowed only for initial API versions 0.y.z (with x=0).
Extensions are post-fixed to the API version numbers and separated from it by a hyphen "-". m and n are numbers starting at 1.
All extensions must have a number (so just "-alpha" or "-rc" is not allowed) and should be minimally "-alpha.1" or "-rc.1").
Precedence example: 1.0.0 < 1.1.0-alpha.1 < 1.1.0-alpha.2 < 1.1.0-rc.1 < 1.1.0-rc.2 < 1.1.0 (public-release)
NOTE: a public-release API version shall have no extension in the API version filed field of the OAS definition file, only the major.minor.patch version number as described in the previous section.
...
Exception: For initial API versions:
- 0.y.z, the full version 0.y.z may be include in the URL, e.g. qod/v0.y.z, to simplify testing of API implementations during initial API development.
- In this exception case, the y is used for major (breaking) changes, and the z is used for minor (non-breaking) changes.
- The dot (".") is kept for readability reasons. See initial API version section below for exception examples.
API name
The API name used in this document is the segment in the url field in the OAS definition file before the segment holding the API version.
...
- Initial API versions only exist for new APIs. They are API versions with x = 0 (API versions 0.y.z, with or without version extension)
- An initial API version may exist for several minor version numbers without extensions, but should at some point mature to become an initial alpha API version: api-0.y.z-alpha.1
- During initial API version development, the API version in the URL shall also include the full y version number v0.y .z (with dots). This is to simplify the testing of different initial API versions..
- In initial API versions, enable testing during rapid development. The guideline is that the y number is increased with breaking changes, the z number is increased with non-breaking changes (see also the exception below).
Exception: for initial API versions:
A breaking change results in an API version change from 0.y.z-extension.n to an API version: 0.y+1.0. Example: 0.9.0-alpha.m or 0.9.0-rc.n → 0.10.0
- A non-breaking change results in an API version change from 0.y.z-extension.n to an API version. 0.y.z+1. Example: 0.9.0-alpha.m or 0.9.0-rc.n → 0.9.1
- After this, -alpha.m and -rc.n extensions can again be applied throughout the initial API version development.
- Once a first public-release API version x.y.z has been created (x > 0), normally no further initial API versions (x = 0) are allowedshall be created.
alpha (alpha) API version
- An alpha API version (extension
alpha.m) is an intermediate API version with changes with respect to a previous API version. - The purpose of an -alpha API version is to support rapid development of an API and testing of its implementation for feedback purposes.
- An alpha API version provides the relevant alpha items of the readiness checklist. A release package is optional.
- An alpha API version cannot be part of a CAMARA meta-release.
- It needs to go through the below API pre-release and release steps first.
...
- A release-candidate API version (extension -rc.n) is a pre-release version of an API which is stabilized and intended to become the next public-release API version.
- The purpose of a prerelease-release candidate API version is to provide a stable version for implementation and API allow for bug fixing encountered during further API implementation testing. It shall be used to create the API test results and to show it meets the acceptance criteriaall required release assets. - moved to next bullet - remove this bullet - questing on test results is still valid.
- A release-candidate API version shall provides the all relevant rc items of the release checklist, such as API test results.
- A release-candidate API version can only be part of a CAMARA proposed for a meta-release after approval by the Release Management team.
- A release-candidate API version proposed for a meta-release needs to be approved by the Release Management team.
- For a release-candidate API version to be approved for public-release as part of a given meta-release, it needs to provide all the public-release needs to provide all the public-release items on the release checklist.
- Once the The final release-candidate API version is approved by the Release Management team, the needs to go through TSC approval such that its corresponding public-release API version is created by the API team for publication as part of the can be prepared and included in the meta-release.
public-release API version
- A public-release API version (x.y.z with x>0) is a major/minor/patch stable version of an API.
- A public-release API version is published as part of a CAMARA meta-release.
- A public-release API version provides the relevant public items of the release checklist and meets the acceptance criteria of a meta-releasechecklist.
- A next public-release API version is introduced if there are updates to the API definition (major/minor/patch).
- The update of a public-release API version needs to be carefully announced and discussed with API consumers.
- Minor updates or patches to a released API results in the creation of a maintenance branch with its own releases as needed.
- Cumulative minor changes shall be released in the next meta-release, following the normal release process.
- A patch release replaces the released API version in the existing meta-release.
work in progress API version
- A work in progress API version, with "wip" instead of x.y.z as version number, may exist for an API during the time that one or more Pull Requests (PRs) are committed into the branch of a given API versionafter a release tag was created.
- The purpose of a work-in-progress API version is to indicate an that the API is unstable version due to one or more PRs being committed, possibly resulting in temporary inconsistencies.
- Between different PR commits, the API version remains "wip".
- After or with the last PR commit, the next API version pre-release is prepared.
- The maintainers of the API decide on the next API version and the corresponding release assets are created for the next API version.
...