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

Compare with Current View Page History

Version 1 Next »

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 version releases 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