Release management & versioning - proposal

This section gives an overview of the proposed handling of API versions and their handling in the release management process.

Highlights of the proposal

• Use of CAMARA internal alpha (-alpha.m) API versions (with version extensions) for API development management purposes
• Use of CAMARA internal release-candidate (-rc.n) API versions (with version extensions) for release management purposes
• Externally released APIs (public-release API versions of a meta-release) only have API version number x.y.z (semver 2.0), no version extension
• People are free to use alpha or release-candidate API versions available in the CAMARA GitHub at their own risk.
• API families are not versioned, nor release-managed, only API versions are release-managed.

It consolidates inputs from 

• Rafal's proposal for the CAMARA API Maturity Levels - proposal - CAMARA Project - Confluence and Herbert's comments
• the inputs from Consolidation Issue for open points release management · Issue #9 · camaraproject/ReleaseManagement (github.com).
• Proposal to establish API Families as Working Groups across API Sub Projects · Issue #7 · camaraproject/ReleaseManagement (github.com)
• Open Issues Consolidated - CAMARA Project - Confluence

This page was discussed on the RM call of 2024-03-26. Feedback was:

• alpha "-alpha.m" API version shall not be considered as a pre-release, but a not-released.
• release-candidate "-rc.n" extensions
• these extension only internally in CAMARA for release management, but not in externally released APIs, which should only have semver numbers.
• API implementers are recommended to start implementation of an API with the first release-candidate API version in order to give feedback on the API definition. The API definition may change following API implementation feedback on the release-candidate, and result in an updated release-candidate.
• Only fully tested release-candidate API versions can become part of a meta-release.

Table of Contents

Definitions

API version

The API version is defined in the "version" field of the OAS definition of an API. Its content must follow Semantic Versioning 2.0.0 | Semantic Versioning (semver.org).

An API version has the format:  x.y.z  where x, y and z are numbers corresponding to MAJOR, MINOR and PATCH releases.

The following bullets are extracted of the semver 2.0 specification (and links to the corresponding spec item):

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

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

The CAMARA API guidelines describe the applicable versioning strategy. NOTE: if this proposal is accepted, some updates of the guidelines may be needed.

API version extensions 

During the API development and release preparation, alpha (-alpha) or release-candidate (-rc) extensions shall be used to identify intermediate versions of an API.  

The notions of alpha and release-candidate API versions, and their related API version extensions, are INTERNAL to the CAMARA project and used only for the development and release management process.

The API version extension is added to the "version" field of the OAS definition of an API, as well as to the URL (see below). Its content must follow the here described syntax and semantics.

The following API version extensions shall be used in the API version:

• alpha API versions: -alpha.m
• release-candidate API versions: -rc.n
• no extension - this is allowed only for initial API versions 0.y.z, and only until the first alpha API version 0.y.z-alpha.1 has been created.

Extensions are post-fixed to the API version numbers and separated from it by a hyphen "-". m and n are numbers.

All extensions must have a a number (so just "-rc" is not allowed and should be "-rc.1")

Precedence example: 1.0.0 < 1.1.0-alpha.1 < 1.1.0-alpha.2 < 1.1.0-rc.1 < 1.1.0-rc.2 < 1.1.0 (public-release)

NOTE: a public-release API version shall have no extensions, only the major.minor.patch version number as described in the previous section.

API version in URL

The API guidelines contain the following approach for defining the API endpoint URL:

servers:
  - url: "{apiRoot}/qod/v2"
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root

The apiRoot is to be adapted by the implementer of the API endpoint (the API provider).

Once a public-release API version is created and published as part of a meta-release, the API version in the URL of a released API shall ONLY contain the MAJOR digit of the API version, e.g. "v2" in the above example.

For alpha and release-candidate API versions, the API version extension shall be included in the URL, but without any hyphens or dots.

Example: in the URL of an alpha API version 2.y.z-alpha.1, the version in the URL is v2alpha1.

Exception: For initial API versions 0.y.z, the second version number may be include in the URL, e.g. v0.y, to simplify testing of API implementations during API development. In this exception case the "." is kept for readability reasons.

initial API version

• Initial API versions only exist for new APIs. They are API versions with x = 0 (API versions 0.y.z-extension.n)
• An initial API version may exist for several minor version numbers without extensions, but should at some point become an initial alpha API version 0.y.z-alpha.1
• The API version in the URL may include the major and minor version numbers: v0.y to enable testing during rapid development. Applies to initial API versions ONLY
• Once a first public-release API version has been created (x > 0), no further initial API versions (x = 0) are allowed.

• Exception: an initial alpha or release-candidate API version 0.y.z-extension.n may evolve to an initial API version 0.y+1.0 in case of a breaking change or to an initial API version. 0.y.z+1 in case of non-breaking changes. Example: 0.9.0-rc.3 → 0.9.1 (non-breaking change) or 0.10.0 (breaking change).After this -alpha.m and -rc.n extensions can again be applied.

alpha (alpha) API version

• An alpha API version (extension  alpha.m) is an intermediate API version with changes with respect to a previous alpha API version.
• The purpose of an -alpha API version is to support rapid development of an API and its implementation for testing purposes.
• An alpha API version provides the relevant alpha items of the readiness checklist.
• An alpha API version cannot be part of a CAMARA meta-release. 
• It needs to go through the below API pre-release and release steps first.

release-candidate (rc) API version

• A release-candidate API version (extension -rc.n) is a pre-release version of an API with stabilized changes with respect to the latest public-release API version.
• The purpose of a pre-release API version is to provide a more stable version and prepare the API readiness for public-release as part of a meta-release.
• A release-candidate API version provides the relevant rc items of the release checklist.
• A release-candidate API version cannot be part of a CAMARA meta-release. 
• For a release-candidate API version to be accepted for public-release in a given meta-release, it needs to provide all the public-release items on the release checklist.
• Once the release-candidate API version is approved by the release management process for publication as part of a meta-release, the public-release API version is created.

public-release API version

• A public-release API version (x.y.z with x>0) is a major/minor/patch stable version of an API published as part of a meta-release.
• A public-release API version provides the relevant public items of the release checklist.
• A next public-release API version is introduced if there are updates to the API definition (major/minor/patch).
• The update of a public-release API version needs to be carefully announced and discussed with API consumers.
• A public-release API version is part of a CAMARA meta-release

development API version

A developmenet version of an API is any of the following API versions

• an initial API version apiname-0.y.z
• a alpha API version apiname-x.y.z-alpha.m

pre-release

A pre-release refers to a release-candidate API version apiname-x.y.z-rc.m.

A pre-release has an associated GitHub release package with a "pre-release" tag.

public-release

A public-release API version is an API version meeting all checklist requirements such that it can be published as part of a meta-release.

NOTE: all CAMARA development and pre-release API versions are also publicly available and can be used, but changes may happen to such API versions without notice.

release

An API release can refer to either a release-candidate or a public-release version of an API.

meta-release

A meta-release is a set of public-release API versions made available at a given point in time (September and March).

All API versions of a given meta-release shall be using the Commonalities and Identity and Consent Management releases that are part of that same meta-release.

Releasing API versions

API version throughout the release process

The following picture gives an overview of the API versions that an API can go through from inception to release.

The following section describe the details on naming, release assets, and the steps to produce a public-release API version as part of a meta-release.

API release assets & naming conventions

During the development, release preparation and release of an API version, multiple intermediate pre-releases for initial, alpha or release-candidate API versions may be created, and a final public-release API version is created.

A release requires the creation of an associated set of API release assets.

For a given API version, its release consists in creating the following set of API release assets:

• the API version in the OAS version field in the API definition file
• the API major version in the URL defined in the API definition file
• the Github branch for the API version: apiname-x.y.z, with extension as applicable
• the API version tag on that branch apiname-vx.y.z, with extension as applicable
• a GitHub release package, tagged "latest" or "pre-release", containing the API Sub-project repo for the branch

In case of multiple APIs managed in the same API Sub-project, each API shall be developed in a separate folder.

Release are handled per API, and the apiname is part of the branch and tags names to distinquih releases of APIs in the same API family.

To create an API version (pre-)release, the API (pre-)release assets need to be created with naming rules as indicated in the below table.

This is illustrated in the following figure:

The following rules shall apply: 

• With the exception of initial API versions, all pre-release API versions must have an API extension.
• An initial or alpha API version may have a GitHub release package, which must have the "pre-release" tag
• A release-candidate and public-release API version must have a GitHub release package
• Only the latest release packages of an API version may have the tag "latest".

Special case: initial API versions (0.y.z)

A newly introduced API is in the main branch and has API version 0.1.0.

The API version v0.y.z handling is slightly different from API versions > 0, as one or more working branches for initial API versions may be created differing in the minor version number during initial API development in the v0 context without creating GitHub release packages for these branches. Branch names are apiname-0.y.z, and optionally creating release packages for these branches. 

Examples: 0.1.0 < 0.1.1< 0.2.0 < 0.2.1 < 0.3.0, etc.

Once an API version 0.y.z is deemed sufficiently stable, a first apiname-0.y.z-alpha.1 branch shall be created with the corresponding GitHub release package.

From this point onward, the below API (pre-)release steps apply.

The first public release of an API version 0.y.z results in API version 1.0.0.

Preparing an API (pre-)release

An API Sub-project can create as many initial or alpha API versions as they want during API development in preparation for the release.

For API version > v0, the next API version number is defined and does NOT change during API development and release preparation. Only the API version extensions and their numbers may change. 

To prepare the release of an API version, one or more release-candidate API versions MUST be created as follows:

• At the M3 release milestone: when the API is agreed stable for release by the API Sub-project.
• At the M4 release milestone: the final release-candidate API version is delivered for meta-release approval.

Releasing an API

A public-release API version is created when the release-candidate API version is approved for a meta-release.

• At the M5 release milestone, the final API version (without any extension) is created in its branch and with its release package, and included in the meta-release.

Updating an API

Updates to a public-release API version need to be carefully planned.

To manage updates of API versions, the semver 2.0 versioning applies to the API version number as follows:

• changes in the major number when creating non-backward compatible changes to the API
• changes in the minor number when creating backward compatible changes to the API
• changes in the patch 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 branch apiname-1.1.0-alpha.1. 
• Several intermediate alpha branches 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 apiname-1.1.0 branch and release package ("latest") for the new public-release API version 1.1.0.

API family

The notion of API family will not be managed as part of release management. CAMARA releases only consider API versions.

It is recommended to adopt the proposal to make the API family a working group, and have the API sub-project focus on the development of one API or a set of closely related APIs of which the version will be the same and evolve together. Ig versions may evolve separately, it indicates they should be handle in separate sub-projects.

See Herbert's proposal here: Proposal to establish API Families as Working Groups across API Sub Projects · Issue #7 · camaraproject/ReleaseManagement (github.com)

This will reduce the number of meetings and reporting load with the increasing number of APIs, and facilitate moving APIs from one family to another, or combining APIs from multiple families into into into family.

NOTE: if multiple API files are managed in one API Sub-project, each API shall have its own folder, such that release branches and release packages can be created with a focus on a specific API.

API release checklist

NOTE: This proposal can be fed back into GitHub as needed.

The following table identifies the items that need to be provided for an API version for a particular release.

It is intended as a checklist for the API sub-projects to prepare an API version release.

In addition the following are the release assets that need to be provided to support the release of an API version:

Examples

The following are examples of the API release asset naming for the various API versions throughout the API version's lifecycle. 

API version 0.y.z (initial API development and first release)

API version x.y.z (x>0) (public-release API updates)

The following table illustrates the usage of versions and version extensions throughout the API lifecycle for the 3 different types of update: minor, major, patch.

Minor update of API version

Patch update of API version

Major update of API version