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.