You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

The following types of API versions are used throughout an API's life cycle:

  • initial (0.y.z) or alpha (x.y.z-alpha.m) API versions (with version extensions) for CAMARA internal API rapid development purposes
  • release-candidate (x.y.z-rc.n) API versions (with version extensions) for CAMARA internal API release bug fixing purposes
  • public-release (x.y.z) API versions 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 (wip) API versions used during the development of an API in between pre-releases. Such API versions cannot be released and is not usable by API consumers.

The use of the different API versions throughout the API life cycle is illustrated in the following figure.

The next sections provide the definitions and the description of the release management process for different versions of an API, and illustrates this by examples.

Evolution of a public-release API

Evolution of a public-release API version need to be carefully planned. this is especially true for breaking changes, but also for non-breaking changes such as new optional functional extensions.

To manage evolution of a public-release API version, the semver 2.0 versioning applies to the API version number x.y.z as follows:

  • changes in the major (x) number when creating non-backward compatible / breaking changes to the API
  • changes in the minor (y) number when creating backward compatible changes to the API
  • changes in the patch (z) number when correcting an error of the API

During the development of an API version update, all pre-release API versions need to get a version extension so its release can be managed properly.

Example for a backward-compatible update of a public-release API version 1.0.0, resulting in API version 1.1.0:

  • Develop the 1.1.0 update on the main branch
  • Once sufficiently stable, create a new API version api-1.1.0-alpha.1 by tagging the main branch
  • Several intermediate alpha API versions may be created, with or without release packages
  • Then one or more intermediate release-candidate API versions (rc branches + release packages) may be created (see example table below).
  • The last release-candidate API version will be proposed for meta-release. 
  • After meta-release approval, create the new public-release API version 1.1.0 for public-release (tag and release package ("latest")).

Maintenance of a public-release API

Once an API has been published as part of a meta-release, situations may occur where minor or patch changes to this API need to be made.

  • In this case a dedicated branch will be opened for the maintenance of the API.
  • The changes are proposed through Pull Request (PRs) and committed to the maintenance branch.
  • In this case, a maintenance branch is opened to which contributions through PRs will be committed. The version of the resulting updated API shall follow the semver rules. A new public-release may be created immediately without waiting for the next meta-release.
  • The availability of the new release should be reflected through the API release tracker page.
  • No labels