Page History

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

Synthesis:

The Release Management process is based on API versions and their associated release assets. It uses

• Use of initial or alpha (-alpha.m) API versions (with version extensions) are used for CAMARA internal API development purposes
• Use of release-candidate (-rc.n) API versions (with version extensions) are used for CAMARA internal API release management purposes
• Use of public-release API versions are used for API versions that are part of a meta-release. These API versions only have API version number x.y.z (semver 2.0), no version extension.
• People are free to use initial, 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.
• API versions are created identified by putting a an API version tags on the main or on a release branch (the latter in case of evolution of changes to a released APIs).
• An API release are created by putting a release tag on the main or on a release branch (in case of evolution of released APIs), and by creating a GitHub release package.consists in creating the related set of API version assets and delivering them in an API version release package. 
• Note 1: People are free to use initial, alpha or release-candidate API versions available in the CAMARA GitHub at their own risk.
• Note 2: API families are not versioned, nor release-managed, only API versions are release-managed.

The following sections provide the definitions and the description of the release management processes, and illustrates by examplesThe following sections provide the details on definitions and the processes, and illustrates by examples.

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

...

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

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 API name is part of the tags names to distinguish releases of APIs in the same API family.

API version changes

API version changes

To create an API version (pre-)release, the API (pre-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.

...

• Develop the 1.1.0 update on the main branch
• Once sufficiently stable, create a new branch apinameapi-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 apinameapi-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 have one API per 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)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.

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.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 GitHub as needed.

...

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

...

Patch update of API version

Major update of API version