...
- Initial API versions only exist for new APIs. They are API versions with x = 0 (API versions 0.y.z-extension.n, with or without version extension)
- An initial API version may exist for several minor version numbers without extensions, but should at some point mature in 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 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 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 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.
...
However, for initial API versions (with x=0), there are some exception cases that may occur . The below table provides guidelines on how to handled the API version in these cases:
...
during initial development of an API:
A breaking change: results in an API version change from api-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.
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 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+1.0-alpha.1 | api-0.y.z+1 / api-0.y.z+1-alpha.1 |
| api-0.y.z-rc.n | api-0.y+1.0 / |
api-0.y+1.0-alpha.1 |
/ api-0.y |
+1.0- |
rc.1 | api-0.y.z |
| +1 / api-0.y.z+1 |
| -alpha.1 |
| / api- |
| 0.y.z+1 |
| - |
| rc.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.
Special case: initial API versions (0.y.z)
A newly introduced API is in the main branch and has API version 0.1.0.
The API version v0version 0.y.z handling is slightly different from API versions > 0x>0, as one or more working branches for initial API versions may be created differing in the minor version number during initial API development in the v0 context without creating GitHub release packages for these branches. Branch names are apiname-0.y.z, and optionally creating release packages for these branches.
...