Page History

DRAFT FOR REVIEW (please use comments on the page - when selecting text the comment button will appear)

This section gives the overview of the handling of API versions in throughout the release management process.

...

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

...

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.  

...

NOTE: a public-release API version shall have no extension in the API version filed of the OAS definition file, 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:

...

Exception: For initial API versions 0.y.z, the full version 0.y.z may be include in the URL, e.g. v0.y.z, to simplify testing of API implementations during API development. In this exception case the dot (".") is kept for readability reasons. See initial API version section below for exception examples.

API name

The API name used in this document is the segment in the url field in the OAS definition file before the segment holding the API version.

Example: for the above url: "{apiRoot}/qod/v2", the API name is qod.

initial API version

• Initial API versions only exist for new APIs. They are API versions with x = 0 (API versions 0.y.z, with or without version extension)
• An initial API version may exist for several minor version numbers without extensions, but should at some point mature to become an initial alpha API version: api-0.y.z-alpha.1
• During initial API version development, the API version in the URL shall include the full version number v0.y.z (with dots) to enable testing during rapid development. The guideline is that the y number is increased with breaking changes, the z number is increased with non-breaking changes (see also the exception below).

• Exception: for initial API versions:  

  • A breaking change results in an API version change from 0.y.z-extension.n to an API version: 0.y+1.0. Example: 0.9.0-alpha.m or 0.9.0-rc.n → 0.10.0

  • A non-breaking change results in an API version change from 0.y.z-extension.n to an API version. 0.y.z+1. Example: 0.9.0-alpha.m or 0.9.0-rc.n → 0.9.1
  • After this, -alpha.m and -rc.n extensions can again be applied throughout the API version development.
• Once a first public-release API version x.y.z has been created (x > 0), no further initial API versions (x = 0) are allowed.

alpha (alpha) API version

• An alpha API version (extension alpha.m) is an intermediate API version with changes with respect to a previous API version.
• The purpose of an -alpha API version is to support rapid development of an API and testing of its implementation for feedback 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 which is stabilized and intended to become the next public-release API version.
• The purpose of a pre-release API version is to provide a stable version for implementation and API testing. It shall be used to create the test results and to show it meets the acceptance criteria.
• A release-candidate API version provides the relevant rc items of the release checklist.
• A release-candidate API version can only be part of a CAMARA meta-release after approval by the Release Management team.
• 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.
• A public-release API version is published as part of a CAMARA meta-release.
• A public-release API version provides the relevant public items of the release checklist and meets the acceptance criteria of a meta-release.
• 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.

work in progress API version

• A work in progress API version, with "wip" instead of x.y.z, may exist for an API during the time that one or more Pull Requests (PRs) are committed into the branch of a given API version.
• The purpose of a work-in-progress API version is to indicate an unstable version due to one or more PRs being committed, possibly resulting in temporary inconsistencies.
• Between different PR commits, the API version remains "wip".
• After or with the last PR commit, the next API version is prepared.
• The maintainers of the API decide on the next API version and the corresponding release assets are created for the next API version.

pre-release

The term pre-release can be used to refer to an alpha API version or a release-candidate API version.

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

release

The term release can be used to refer to either a pre-release 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 aligned to the Commonalities and Identity and Consent Management releases that are part of that same meta-release.

API version tag

An API version tag is a GitHub tag placed on the main or a selected branch to allow locating the corresponding API version in the repository.

API version release package

An API version release package is created using the GitHub release mechanism. It consists in a zip file that has a snapshot of the API Sub-project repository with the content located using the API version's tag.

Releasing API versions

API versioning throughout the release process

During the development, release preparation and release of an API version,

...

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 version assets & naming conventions

For a given API version, its release consists in creating the set of API version assets with naming as indicated in the below table.

...

• the API version (OAS file) is the version field of the API OAS definition file
• the API version extension (OAS file) is the extension that can be added to the version field of the API OAS definition file
• the API version in URL (OAS file) is the a "v" followed by the API major version number placed in the URL field of the API OAS definition file
• the API version tag is the GitHub tag put on the main or update branch allowing to retrieve the API version, e.g. api-x.y.z, with extension as applicable
• the API version release package, tagged "pre-release" or "latest", containing the zipped version of the whole API Sub-project repository.

API version changes

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.

...

• 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 an API version release package, which must have the "pre-release" tag
• A release-candidate and public-release API version must have an API version 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 "wip", until the first API version is created: api-0.1.0.

...

The first public-release API version 1.0.0 is created from the last agreed and accepted API version api-0.x.y-rc.n

Developing an API

During the development of an API several contributions can be made by different people from their private forks or by maintainers of eth API on a development branch.

...

• The first/all PRs shall setthe version field of the APIOAS definition file(s) to “wip”.
• This wip versions shall remain until the project maintainers decide to tag the API as Vnext
• If the Vx.y.z has an associated release package, a release packages shall be created for Vnext.
• Only maintainers can create development branches.
• Other developers should fork the repo and do PRs from there.
• All PRs shall be approved by maintainers before being committed.
• Once all PRs are merged, the last PR shall updated the version field of the API OAS definition file(s) to Vnext
• The Vnext release tag shall be applied to the branch.

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.

...

• 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 with its release package, and included in the meta-release.
• Inclusion in a meta release is done by adding the required information for the API version on the meta-release page.

Updating an API

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

...

• 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 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 api-1.1.0 branch and release package ("latest") for the new public-release API version 1.1.0.

Meta-release approval for an API version

• To be approved for meta release, the API version must provide all the public items of the release checklist and meet the meta release acceptance criteria.
• The API Sub-project shall announce ther intention for public-release API vesion by documenting the references to the relevant release-candidate API version on the meta release page.
• After check by the release management team, approval is documents there.
• Once approved the API Sub-project shall create the public-release API version and its API version assets.
• Finally the API sub-project shall update the meta-release page with the reference to the public-release API version.

API family

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

...

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

API release checklist

NOTE: This proposal can be fed back into Commonalities project as needed or moved here.

...

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

...