...
An API version release package is created using the GitHub release mechanism. It consists in a zip file that has a snapshot of the API Sub-project repository with the content located using the API version's tag.
Releasing API versions
API
...
versioning throughout the release process
During the development, release preparation and release of an API version,
...
The following section describe the details on naming, release assets, and the steps to produce a public-release API version as part of a meta-release.
API
...
version assets & naming conventions
For a given API version, its release consists in creating the set of API release version assets with naming as indicated in the below table.
...
Release are handled per API, and the API name is part of the tags names to distinguish releases of APIs in the same API family.
API version changes
To create an API version (pre-)release, the API (pre-)release assets need to be created with naming rules as indicated in the below table.
This is illustrated in the following figure:
The following rules shall apply:
- With the exception of initial API versions, all pre-release API versions must have an API extension.
- An initial or alpha API version may have a GitHub an API version release package, which must have the "pre-release" tag
- A release-candidate and public-release API version must have a GitHub have an API version release package
- Only the latest release packages of an API version may have the tag "latest".
...
The below table provides guidelines for the initial API versioning exceptions. The semver numbering sequencing does apply for initial API versions. Examples: 0.1.0 < 0.1.1< 0.2.0 < 0.2.0-alpha.m < 0.2.0-rc.n < 0.2.1 < 0.3.0, etc.
| API version | next API version for breaking change | next API version for non-breaking change |
|---|---|---|
| api-0.y.z | api-0.y+1.0 | api-0.y.z+1 |
| api-0.y.z–alpha.m | api-0.y+1.0 | api-0.y.z-alpha.m+1 / api-0.y.z+1 |
| api-0.y.z-rc.n | api-0.y+1.0 | api-0.y.z-rc.n+1 / api-0.y.z+1 |
In the above table, the choice between 2 proposed next API version options is done by the API maintainers based on the estimated stability of the API with respect to the introduced changes.
...
The first public-release API version 1.0.0 is created from the last agreed and accepted API version api-0.x.y-rc.n
...
Developing an API
- Vx.y.z: any API version (with or without extension) to which changes are to be applied through PR(s).
- Vnext: the tag of the next version with respect to Vx.y.z after the PRs have been applied.
- This can be applied to any Vx.y.z as needed for patches, updates or evolutions.
- The first/all PRs shall setthe version field of the APIOAS definition file(s) to “wip”.
- This wip verions shall remain until the project maintainers decide to tag the API as Vnext
- If the Vx.y.z has an associated release package, a release packages shall be created for Vnext.
- Only maintainers can create development branches.
- Other developers should fork the repo and do PRs from there.
- All PRs shall be approved by maintainers before being merged.
- Once all PRs are merged, the last PR shall updated the version field of the API OAS definition file(s) to Vnext
- The Vnext release tag shall be applied
...