Copy of Planning and releasing API versions

TEMPORARY COPY - TO BE REMOVED WHEN DONE

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

The Release Management process is based on creating releases for API versions, aligned with given Commonalities and ICM release in a given meta-release.

Note 2: API families are not versioned, nor release-managed. Only API versions are release-managed.

T

The rest of the text in this section can be removed once the proposal is agreed.

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
• Multiple APIs in an API Sub-project (dedicated meeting)

Table of Contents

i

Releasing API versions

API versioning throughout the release process

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 is created for the API version for inclusion in the meta-release

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 above table

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 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 package of an API version may have the tag "latest".

Version of new APIs (wip)

A newly introduced API is in the main branch and has API version in the API URL set to "vwip" (see table above),

It stay like that until the first initial API version (with x=0), e.g. api-0.1.0 or api-0.1.0-alpha.1, is decided to be created by the API Sub-project team.

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

While public-release API versions follow the semver standard, initial API versioning uses the version numbers exceptionally as follows:

• the major version (x) number is 0 in all cases
• the minor version (y) number is used for breaking changes
• the patch version (z) number is used for non-breaking changes
• version extensions can be used but a release candidate API version may go back to an alpha API version or to an initial API version without any extension. 

The below table provides guidelines for the initial API versioning. The semver numbering sequencing does apply for initial API versions. 

Examples: 0.1.0 < 0.1.1< 0.2.0 < 0.2.0-alpha.m < 0.2.0-rc.n < 0.2.1 < 0.3.0, etc.

In the above table, the choice between 2 proposed next API version options is done by the API maintainers based on the estimated stability of the API with respect to the introduced changes. 

In addition, the normal API version evolution through -alpha.m and -rc.n extensions is applicable throughout the API version development.

Once an initial API version 0.y.z is deemed sufficiently stable, a first alpha API version api-0.y.z-alpha.1 shall be created. The creation of a release package is optional for initial and alpha releases.

From this point onward, the below API (pre-)release steps apply and further alpha and release-candidate API versions with their corresponding API release assets as per the above table shall be created as needed.

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

Developing an API (wip)

During the first development of an API, and in between API releases, several contributions can be made by different people from their private forks or by maintainers of the API on their development branch.

The contributions are proposed through Pull Request (PRs) and committed to the target branch: main 

NOTE. An exception is when changes need to be made to a public-release API version for maintenance/patch reasons (see API maintenance section) in which case a maintenance branch is opened to which contributions through PRs will be committed. The release of the resulting new public-release API version shall follow the API version shall follow the semver rules.

While multiple PRs are being committed to the target branch, unstable API versions may exist. To avoid that people use such unstable versions, the following guideline shall be applied:

• The first PR commit will ensure that the API will get the version "wip" instead of x.y.z. 
• All subsequent PR commits shall maintain that same API version as "wip"
• Once all PR commits are done and stability, usability and consistency of the updated API is agreed on, the maintainers create the next API version tag on the ytaret branch.
• This new version can now be used by API consumers who want to test the new pre-release version.

The following figure illustrates the work-in-progress version of the API created in this process.

Here are explanations on the above figure:

• rx.y:  the release of any API version (with or without extension) to which changes are to be applied through PR(s).
• rnext: the tag of the next release of the API version with respect to rx.y after the PRs have been committed and API stability is reached.

This work-in-progress process can be applied to any release as needed for patches, updates or other evolutions of APIs

• The first/all PRs shall set the version field of the API OAS definition file(s) to “wip”.
• This wip versions shall remain until the project maintainers decide to release the API version (rnext)
• If the rx.y has an associated release package, a release packages shall be created for rnext.
• 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 the new API version
• The API version shall be released under the rnext release tag applied to the branch.

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 their intention for public-release API version by adding the relevant release-candidate API version on their API release tracker 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.

It is recommended to have one API per API sub-project to facilitate the release management and versioning of APIs.

If multiple API are managed in one API Sub-project, each API file shall have its own folder, such that release packages can be created with a focus on a specific API. The API name and the API version of this API shall be used in the naming of the API version tag and API version release package. However, as the release package will also include all other APIs of the Sub-project, this may lead to confusion.

An API Sub-project may also decided to release all APIs in the same API family always at the same time with the same API version. In this case,

• all API files in the release must have the same API version.
• instead of the API name, the API Sub-project name shall be used in the API version tag and the API version release package name.

If later on one API of the API family requires a separate evolution with its own version number, then this API shall be put in its own API Sub-project.

The grouping of APIs into families or other groupings, e.g. by related working groups, can be done easily using a CAMARA wiki page.

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

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

The following are examples of the API release asset and release 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