...
- 1.0.0 → 1.1.0-alpha.1 → ... → 1.1.0-alpha.m → 1.1.0-rc.1 → ... → 1.1.0-rc.n → 1.1.0 (next stable public-release)
- 0.5.0 → 0.6.0-alpha.1 → ... → 0.6.0-alpha.m → 0.6.0-rc.1 → ... → 0.6.0-rc.n → 0.6.0 (next initial public-release)
- For PATCH changes, the API Sub Project can decide to either
- apply the CAMARA API release process, as for MAJOR and MINOR changes resulting in a new API version x.y.z+1
- 1.0.0 → 1.0.1-alpha.1 → ... → 1.0.1-alpha.m → 1.0.1-rc.1 → ... → 1.0.1-rc.n → 1.0.1 (next stable public-release)
- implement a PATCH updates using a maintenance branch for a shorter release cycle as follows:
- apply the CAMARA API release process, as for MAJOR and MINOR changes resulting in a new API version x.y.z+1
- A dedicated maintenance branch shall be opened for the PATCH of the API
- the branch name shall be maintenance-x.y.z where x.y.z is the current API version being patched
- The changes are proposed as usual through Issues and Pull Request (PRs) and commits to this maintenance branch.
- The API update results in a maintenance release with the public-release API version x.y.z+1 (per semver 2.0.0)
The PATCH of the API for the maintenance release will be merged into the next MAJOR or MINOR API release on the main branch
- The maintenance branch shall continue to exist for further PATCH updates of this API (incrementing z)
- A dedicated maintenance branch shall be opened for the PATCH of the API
Update 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 updates of a stable public-release API version (API version x.y.z with x>0), the semver 2.0 versioning applies.
Example for a non-breaking update of a public-release API version 1.0.0, resulting in a new release with API version 1.1.0:
- Develop the 1.1.0 update on the main branch. The first PR updates the version to wip, and the URL to contain vwip.
- Once sufficiently stable, update the new API version to 1.1.0-alpha.1.
- Several intermediate alpha API versions may be created.
- Then one or more intermediate release-candidate API versions may be created.
- The last release-candidate API version will be proposed for meta-release.
- For meta-release approval, create the PR for the new public-release API version 1.1.0.
- After meta-release approval, create the release for the new public-release API version 1.1.0, with its release tag rx+1.n and release package ("latest")).
If there is a real need to support multiple public-release API versions, 2 consecutive major versions should be the maximum (this is by experience, not a convention or requirement).
To implement PATCH updates of a public-release API version, a maintenance branch shall be created,
...
It is recommended to have maximally 2 consecutive public-release API versions available.
Breaking and non-breaking changes
...