Page History

...

Highlights of the proposal

• Use of CAMARA internal work-in-progress alpha (-wipalpha.m) and release-candidate (-rc.n) API versions (with version extensions) 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 (public-release API versions of a meta-release) only have API version number x.y.z (semver 2.0), no version extension
• People are free to use pre-release 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

...

This page was briefly discussed on the RM call of 2024-03-19. Initial feedback was:

• use work in progress "-wipalpha.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 externally released APIs, which should only have semver numbers.
• API implementers are free to use these pre-release versions as they see fit, but there is no guarantee from CAMARA side that they will not change. 

...

During the API development and release preparation, "work-in-progressalpha" (-wipalpha) or "release-candidate" (-rc) extensions shall be used to identify intermediate pre-releases of an API.  

The notions of work-in-progress alpha and release-candidate API versions and the related API version extensions are INTERNAL to the CAMARA project and used only for the release management process.

...

The following API version extensions shall be used in the API version:

• work-in-progress alpha API versions: -wipalpha.m
• release-candidate API versions: -rc.n
• no extension - this is allowed only for initial API versions 0.y.z, and only until the first work-in-progress alpha API version 0.y.z-wipalpha.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-wipalpha.1 < 1.0.0-wipalpha.2 < 1.1.0-wipalpha.1 < 1.1.0-wipalpha.2 < 1.1.0-rc.1 < 1.1.0-rc.2 < 1.2.0 (public-release)

...

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

This simplifies testing of the API implementations during API development.

...

• 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 alpha API version 0.y.z-wipalpha.1
• No further initial API versions may be created once the first work-in-progress alpha API version 0.y.z-wipalpha.1 has been created for the API.
• Once a first public-release API version has been created, no further initial API versions are allowed.

...

alpha (alpha) API version

• A work-in-progress alpha API version (extension -wipalpha.m) is an intermediate, pre-release API version with changes with respect to the latest public-release API version.
• The purpose of a -wip alpha API version is to test an evolution of the API by the developer community.
• A work-in-progress alpha API version provides the relevant wip alpha items of the release checklist.
• A work-in-progress 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.
• A work-in-progress alpha API version can be used by testers of the API

...

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

...

During the development, release preparation and release of an API version, multiple intermediate pre-releases for initial, work-in-progress alpha or release-candidate API versions may be created, and a final public-release API version is created.

...

...

• With the exception of initial API versions, all pre-release API versions must have an API extension.
• An initial or work-in-progress alpha API version may have a GitHub release package, which must have the "pre-release" tag
• A release-candidate and public-release API version must have a GitHub release package
• Only the latest release packages of an API version may have the tag "latest".

...

Once an API version 0.y.z is deemed sufficiently stable, a first apiname-0.y.z-wipalpha.1 branch shall be created with the corresponding GitHub release package.

...

An API Sub-project can create as many initial or work-in-progress alpha API versions as they want during API development in preparation for the release.

...

• Develop the 1.1.0 update on the main branch
• Once sufficiently stable, create a new branch apiname-1.1.0-wipalpha.1. 
• Several intermediate wip 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 apiname-1.1.0 branch and release package ("latest") for the new public-release API version 1.1.0.

...

It is intended as a checklist for the API sub-projects to prepare an API version release.

In addition the following are the release assets that need to be provided to support the release of an API version:

...

...

...

...

...