...
The following sections provide the details on definitions and the processes, and illustrates by examples.
The rest of the text in this section can be removed once the proposal is agreed.
It consolidates inputs from
...
- alpha "-alpha.m" API version shall not be considered as a pre-release, but a as not-released.
- release-candidate "-rc.n" extensions
- these extension only internally in CAMARA for release management, but not in externally released APIs, which should only have semver numbers.
- API implementers are recommended to start implementation of an API with the first release-candidate API version in order to give feedback on the API definition. The API definition may change following API implementation feedback on the release-candidate, and result in an updated release-candidate.
- Only fully tested release-candidate API versions can become part of a meta-release.
...
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.
...
- alpha API versions: -alpha.m
- release-candidate API versions: -rc.n
- no extension - this is allowed only for initial API versions 0.y.z , and only until the first alpha API version 0.y.z-alpha.1 has been created.(x=0)
Extensions are post-fixed to the API version numbers and separated from it by a hyphen "-". m and n are numbers.
All extensions must have a a number (so just "-alpha" or "-rc" is not allowed and should be "-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 extensionsextension in the API version filed 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. v0.y.z, to simplify testing of API implementations during API development. In this exception case 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.
Example: for the above url: "{apiRoot}/qod/v2", the API name is qod.
initial API version
- Initial API versions only exist for new APIs. They are API versions with x = 0 (API versions 0.y.z-extension.n)
- An initial API version may exist for several minor version numbers without extensions, but should at some point mature in an initial alpha API version 0.y.z-alpha.1
- During initial API version development, the API version in the URL shall include the full version number v0.y.z (with dots) to 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 alos 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 API version development.
- Once a first public-release API version x.y.z has been created (x > 0), no further initial API versions (x = 0) are allowed.
...