API release management & versioning - proposal

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

Highlights of the proposal

• Use of -wip.m and -rc.n API version extensions internally to the CAMARA API sub-projects for release management purposes
• No use of alpha or beta extensions (internal nor external to CAMARA) as no clear definition is identified.
• Externally released APIs (meta release) only have API version number x.y.z (semver 2.0)
• People are free to use non released API versions available in the CAMARA GitHub at their own risk.
• API families are not versioned, nor release managed, only API versions are managed

It consolidates inputs from 

• Rafal's proposal for the CAMARA API Maturity Levels - proposal - CAMARA Project - Confluence.
• 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 briefly discussed on the RM call of 2024-03-19. Initial feedback was:

• use work in progress "-wip.n" and release candidate "-rc.n" extensions instead of alpha and beta as the latter are not easy to define. These extensions should be only used internally in CAMARA for release management, but not in released APIs, which should only have semver numbers.
• API implementers are free to use these non-released versions as they see fit, but there is no guarantee from CAMARA side that they will not change. 

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 provides some extracts 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.

The API guidelines describe the applicable versioning strategy.

API version extensions 

During the API development and release preparation, "work-in-progress" (-wip) or "release-candidate" (-rc) extensions shall be used to identify intermediate states of an API. 

The notions of work-in-progress and release-candidate API versions are internal to the CAMARA project and used only for the release management process.

The following extensions shall be used in the API version:

• -wip.m
• -rc.n
• no extension - this is allowed only for initial API versions 0.y.z, and only until the first work-in-progress API version 0.y.z-wip.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.

Precedence example: 1.0.0-wip.1 < 1.0.0-wip.2 < 1.1.0-wip.1 < 1.1.0-wip.2 < 1.1.0-rc.1 < 1.1.0-rc.2 < 1.2.0 (released)

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

NOTE: alpha and beta extensions shall not used (as no clear criteria are identified). Only the extensions needed for release management shall be used.

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

Once an API is publicly released, 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.

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

Before API public release, the API definition and endpoint implementation may reflect the extension of the API in the URL, but without any hyphen or dots. 

Example: in the URL the version is v2wip1 for API version 2.y.z-wip.1

This simplifies testing of the API implementations during API development.

pre-release

The term pre-release can be used for any of the following API versions

• an initial API version 0.y.z
• a work-in-progress API version (x.y.z-wip.m)
• a release-candidate API version (x.y.z-rc.m).

NOTE: the term pre-release here is defined to includes more API versions than just the API versions that have a GitHub release package with a "pre-release" tag on it, which only concerns release-candidate API versions.

public-release

The term public-release is used to refer to an API version released as part of a meta-release.

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

meta-release

A meta-release is a set of API versions made publicly 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 release assets & naming conventions

During the development and release preparation of an API version, multiple intermediate pre-releases for initial, work-in-progress or release-candidate API versions may be created, resulting reflected by a set of API release assets

When an API version is released publicly the corresponding set of public-release API assets is created.

For given API version, its release consists of 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
• the API version tag on that branch
• a GitHub release package, tagged "latest" or "pre-release", containing the API Sub-project repo for the branch

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.

The following rules shall apply:

• With the exception of initial API versions, all pre-release and released API versions MUST have an API extension.
• An initial or work-in-progress API version MAY have a GitHub release package, which MUST have the "pre-release" tag
• A release-candidate and released 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.

Examples: release-0.1.0 < release-0.1.1< release-0.2.0 < release-0.2.1 < release-0.3.0, etc. without creating release packages for these branches

Once an API version 0.y.z is deemed sufficiently stable, a first release-0.y.z-wip.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 work-in-progress 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 released 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 with its release package, and included in the meta release.

Updating an API

Updates to a released 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 released 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 release-1.1.0-wip.1. 
• Several intermediate wip 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 release-1.1.0 branch and release package ("latest") for the released updated 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 or more APIs.

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 today, there is a situation where multiple API files are managed in one release package - these should ideally be moved into their own subproject (under one API working group) so that individual release packages can be created, unless there is a way to constrain a Github release package to subset of s a repository ?

API release checklist

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

The following API release checklist items shall be supported:

initial API version

• Initial API versions only exist for new APIs. They are API versions 0.y.z. (without extension).
• Initial API version may exist for several minor version numbers but should at some point become a first work-in-progress API version 0.y.z-wip.1
• Once a first public-release API version exists, no further initial API versions are allowed.

work-in-progress (wip) API version

• The work-in-progress API version (extension -wip.m) indicates an intermediate, non-released API version with changes wrt the latest released API version.
• The purpose of a -wip API version is to test an evolution of the API with the developer community.
• A wip API version cannot be released as part of a CAMARA meta release. 
• It needs to go through the below API pre-release and release steps first.
• a wip API version can be used by testers of the APi

release-candidate (rc) API version

• The release-candidate API version (extension -rc.n) indicates a version of an API with stabilized changes wrt the latest published stable version.
• The purpose of a pre-release API version is to provide a more stable version to show readiness for release
• A rc version of an API cannot be part of a CAMARA meta release. 
• A rc version proposed for a meta release needs to mee all pre-release and release requirements (as per the checklist)
• It needs to be approved by the release management process for publication as part of a meta release

public-release API version

• A public-release API version (x.y.z with x>0) is the latest major/minor/patch stable released version of an API 
• A next public-release API version is introduced if there are updates to the API definition (major/minor/patch).
• The update of 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

Examples

The following are examples of the API release assets and their 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) (released 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 API version update

Patch API version update

Major API version update