Page History

...

• Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable. https://semver.org/#spec-item-4
• Version 1.0.0 defines the (stable)" public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.   https://semver.org/#spec-item-5

  • Patch version Z (x.y.Z | x > 0) MUST be incremented if only backward compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior. https://semver.org/#spec-item-6

  • Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backward compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented. 

  • Major version X (X.y.z | X > 0) MUST be incremented if any backward incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented.

Note: in CAMARA v1.0.0 is considered the first stable public API, while API versions v0.y.z can be public, but are considered unstable (initial).

Precedence example:  1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 < 3.0.0.

...

Update of a public-release API version

Update of Updates to 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.can concern MAJOR, MINOR or PATCH changes to the API definition.

• For MAJOR or MINOR changes, the CAMARA defined API release process applies, going through alpha and release-candidate API versions to create the new release of the API.

Examples:

• • • 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:

• • • 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)

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

...

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:

...

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 very small MINOR or PATCH updates of a public-release API version, a maintenance branch shall be created,

• A dedicated maintenance branch shall be opened for the maintenance of the API.
• The changes are proposed through Issues and Pull Request (PRs) and committed to this maintenance branch.
• The update results in a maintenance release for the public-release API version.
• The resulting updated API version shall follow the semver rules.

• The updates of API for the maintenance release will be merged into a next MAJOR or bigger MINOR or MINOR API updates. 

Breaking and non-breaking changes

...