...
- 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 release package, which must have the "pre-release" tag
- A release-candidate and public-release API version must have a GitHub release package
- Only the latest release packages of an API version may have the tag "latest".
Exception cases
Usually an API will go through the above described steps in the evolution of its version.
...
Special case: initial API versions (
...
0.y.z)
A newly introduced API is in the main branch and has API version "wip", until the first API version is created:
...
api-0.
...
1.0.
While public-release API versions follow the semver standard, initial API versioning uses the version numbers exceptionally as follows:
- the major version number remains 0 in all cases
- the minor version numbers is used for breaking changes
- the patch version number is used for non-breaking changes
- version extensions can be used but a release candidate API version may go back to an alpha API version or to an initial API version without any extension.
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 |
|---|
After this, the normal release process with -alpha.m and -rc.n extensions can again be applied throughout the API version development.
The below table provides naming guidelines for the API version in these exception cases:
api-0.y+1.0
api-0.y.z+1
api-0.y+1.0 / api-0.y+1.0-alpha.1
api-0.y.z+1 / api-0.y.z+1-alpha.1
| api-0.y.z |
api-0.y |
+1 |
. |
0 | api-0.y.z+1 |
In the above table, the choice between the 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.
...
| 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.
In addition, the normal API version evolution through -alpha.m and -rc.n extensions is applicable throughout the API version development.
Once an initial API version 0
Examples: 0.1.0 < 0.1.1< 0.2.0 < 0.2.1 < 0.3.0, etc.
Once an API version 0.y.z is deemed sufficiently stable, a first apinamefirst alpha API version api-0.y.z-alpha.1 branch shall be created with the corresponding GitHub release package.
From this point onward, the below API (pre-)release steps apply and further alpha and release-candidate API versions with their corresponding API release assets as per the above table shall be created as needed.
The first public-release API version v11.0.0 is created from the last agreed and accepted API version apinameapi-0.x.y-rc.n
Initial API versioning - exception cases
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
...