Page History

TEMPORARY COPY - TO BE REMOVED WHEN DONE

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

WARNING: PAGE is currently inconsistent - UPDATE ongoing to decouple release name/number from contained API version(s)

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

...

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

Table of Contents

...

API version type	API version (with extension) (in OAS file)	API version in URL (in OAS file)
initial (x=0)	0.y.z 0.y.z-alpha.m 0.y.z-rc.n	v0.y (exception) v0.yalpham v0.yrcn
alpha	x.y.z-alpha.m	vxalpham
release-candidate	x.y.z-rc.n	vxrcn
public-release (sandbox) (incubated)	0.y.z x.y.z	v0.y (exception) vx
work-in-progress	wip	vwip

Release numbering

For a given API version, a release consists in creating the GitHub release tag and release package which should contain the relevant set of release items as in the release asset table table.

The release package shall contain all assets as defined in the

...

release tag

(on GitHub branch)

...

release package (GitHub repo zipfile)

...

r0.1 ... r0.n

...

optional

...

optional

...

In the above API release asset table, the column headers mean the following:

the release tag is the GitHub tag put on the main or update branch allowing to retrieve the released API version
the 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 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.

...

0.y+1.0

...

0.y.z+1

...

0.y+1.0

...

0.y.z-alpha.m+1 / 0.y.z+1

...

0.y+1.0

...

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.

Image Removed

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

...

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.

API version	next API version for breaking change	next API version for non-breaking change
0.y.z	0.y+1.0	0.y.z+1
0.y.z–alpha.m	0.y+1.0	0.y.z-alpha.m+1 / 0.y.z+1
0.y.z-rc.n	0.y+1.0	0.y.z-rc.n+1 / 0.y.z+1

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.

Image Added

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 setthe version field of the APIOAS 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.

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.

API release checklist

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

The following table identifies the assets 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.

...

Nr

...

API release assets

...

alpha

...

release-candidate

...

public-release

...

sandbox

...

incubated

...

1

...

API definition

...

Y

...

Y

...

Y

...

Y

...

2

...

Test results proving API alignment with Commonalities and ICM guidelines

...

Y

...

Y

...

Y

...

Y

...

3

...

API documentation

...

Y

...

Y

...

Y

...

Y

...

4

...

User stories

...

Y

...

Y

...

Y

...

Y

...

5a

...

Sunny day API test cases and documentation

...

N

...

Y

...

Y

...

Y

...

5b

...

Full set of API test cases and documentation

...

N

...

N

...

Y

...

Y

...

Test results (API test cases passed)

...

N

...

Y

...

Y

...

Y

...

7

...

Release-candidate tested in at least 2 operator implementations

...

N

...

N

...

Y

...

Y

...

8

...

Sandbox release certified and launched in at least 2 operators is needed to become incubated

...

N

...

N

...

N

...

Y

...

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

...

Space shortcuts

Page tree

Versions Compared

Old Version 2

New Version 3

Key

Release numbering

API version changes

Version of new APIs (wip)

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

Developing an API (wip)

API version changes

Version of new APIs (wip)

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

Developing an API (wip)

Meta-release approval for an API version

API family

Meta-release approval for an API version

API family

API release checklist