Page History

This section gives the overview of the handling The API Release Process describes the creation of (pre-)releases of API versions in the release management process.

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

• initial or alpha (-alpha.m) API versions (with version extensions) are used for CAMARA internal API development purposes
• release-candidate (-rc.n) API versions (with version extensions) are used for CAMARA internal API release management purposes
• 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.
• API versions are identified by putting an API version tags on the main or on a release branch (the latter in case of changes to a released APIs).
• An API release 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 examples.

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

This page was discussed on the RM call of 2024-03-26. Feedback was:

• alpha "-alpha.m" API version shall not be considered as a pre-release, but as not-released.
• release-candidate "-rc.n" extensions
• these extension only internally in CAMARA for release management, but not in externally released APIs, which should only have semver numbers.
• API implementers are recommended to start implementation of an API with the first release-candidate API version in order to give feedback on the API definition. The API definition may change following API implementation feedback on the release-candidate, and result in an updated release-candidate.
• Only fully tested release-candidate API versions can become part of a meta-release.

This page was discussed on the RM call of 2024-04-02:

• Feed back on this page was discussed and partially answered. Further discussions on wiki for resolution next week.

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

An API version has the format:  x.y.z  where x, y and z are numbers corresponding to MAJOR, MINOR and PATCH releases.

The following bullets are extracted of the semver 2.0 specification (and links to the corresponding spec item):

• Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable. https://semver.org/#spec-item-4
• Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes. https://semver.org/#spec-item-5

  • Patch version Z (x.y.Z | x > 0) MUST be incremented if only backward compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior. https://semver.org/#spec-item-6

  • Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backward compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented. 

  • Major version X (X.y.z | X > 0) MUST be incremented if any backward incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented.

Precedence example:  1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 < 3.0.0.

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.  

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

The API version extension is added to the "version" field of the OAS definition of an API, as well as to the URL (see below). Its content must follow the here described syntax and semantics.

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

• alpha API versions: -alpha.m
• release-candidate API versions: -rc.n
• no extension - this is allowed only for initial API versions 0.y.z (x=0)

Extensions are post-fixed to the API version numbers and separated from it by a hyphen "-". m and n are numbers.

All extensions must have a number (so just "-alpha" or "-rc" is not allowed and should be "-alpha.1" or "-rc.1")

Precedence example: 1.0.0 < 1.1.0-alpha.1 < 1.1.0-alpha.2 < 1.1.0-rc.1 < 1.1.0-rc.2 < 1.1.0 (public-release)

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:

servers:
  - url: "{apiRoot}/qod/v2"
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root

The apiRoot is to be adapted by the implementer of the API endpoint (the API provider).

Once a public-release API version is created and published as part of a meta-release, the API version in the URL of the public-release API version shall ONLY contain the MAJOR digit of the API version, e.g. "v2" in the above example.

For alpha and release-candidate API versions, the API version extension shall be included in the URL, but without any hyphens or dots.

Example: in the URL of an alpha API version 2.y.z-alpha.1, the version in the URL is v2alpha1.

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

...

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,

• multiple intermediate pre-releases for initial, alpha or release-candidate API versions may be created, and
• a final public-release API version is created.

The following picture gives an overview of the API versions that an API can go through from inception to release.

Image Removed

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.

...

API version tag (GitHub)

(api = API name)

...

API version release package (name = API version tag) (GitHub)

...

 none

-alpha.m

-rc.n

...

v0.y.z (exception)

v0alpham

v0rcn

...

api-0.y.z

api-0.y.z-alpha.m

api-0.y.z-rc.n

...

optional

...

optional

...

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

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

This is illustrated in the following figure:

Image Removed

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

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

• the major version number remains 0 in all cases
• the minor version numbers is used for breaking changes
• the patch version 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 exceptions. 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-0.y+1.0

...

api-0.y.z+1

...

api-0.y+1.0

...

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

...

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

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 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 contributions are proposed through Pull Request (PRs) and committed to the target branch: main in most cases. 

Exception is where changes are made to a public-release API, in which case a maintenance branch is opened to which contribution through PRs will be committed and on which new API version tags will be put.

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

Question tdg: do we need wip.1 ... wip.n ? I would not go there but ... 

Image Removed

Here are explanations on the above figure:

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

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

...

throughout the API lifecycle, and for a given meta-release.

For a meta-release, the API Release Process targets the release of public API versions, aligned with the corresponding Commonalities and ICM public versions.

 The following sections describe how to create an API release and how to report progress on it during the meta-release process.

Definitions

API releases - overview

To prepare the release of a public API version, API versions shall be (pre-)released as follows:

• before M3, release one or more alpha API versions as needed
• to reach M3, release the first release-candidate API version:
  • the release-candidate implements the scope of the target public API version.
  • this pre-release is agreed as ready for API implementation and functional testing.
  • it is aligned with the release-candidate versions of Commonalities and ICM (M1).
• between M3 and M4, release one or more release-candidate API versions as needed
• to reach M4, release the public API version:
  • this is the version ready for inclusion in the meta-release (if so planned).
  • the public API version is aligned with the public versions of Commonalities and ICM (M2).

An API Sub Project can release as many alpha and release-candidate API versions as useful for API development and testing. In between releases, the API version is set to "wip" (to indicate that this API version should not be used).

Public API versions 

Public API versions can have an initial or a stable status.

A public API version is released only if it provides all required API readiness checklist items (see: [API Readiness Checklist](https://wiki.camaraproject.org/display/CAM/API+Release+Process#APIReleaseProcess-APIreadinesschecklist).

Stable public API versions are recommended for use in commercial applications. The user can expect that subsequent public API versions will be backward-compatible with the one they are using, unless explicitly announced otherwise.

Meta-release

To be part of a meta-release, the API Sub Project needs to participate in the meta-release process. For the meta-release, the following needs to be provided:

• the API release tracker (see [API release trackers](https://wiki.camaraproject.org/x/HQBFAQ))
• the expected (pre-)releases at the respective M3 and M4 milestones
• minimally an initial public API version
• the required set of API release assets according to the API readiness checklist (see below).

Example of the use of the API release process

To release a MINOR update of a public API version 1.0.0, resulting in the release of public API version 1.1.0:

• Develop the 1.1.0 updates on the main branch. The first PR shall update the OAS file setting the API version to wip, and the URL to vwip.
• Once sufficiently stable, create a release PR for the API version 1.1.0-alpha.1.
• After release PR approval, create the pre-release rx.1 and publish it on the API release tracker.
• Several alpha API versions 1.1.0-alpha.p may be released, each setting the API version back to "wip" in the first API update PR and evolving the alpha number with each following pre-release (rx.2 - rx.m).
• When the API version is ready, create a release PR for the API version 1.1.0-rc.1
• Several release-candidate API versions 1.1.0-rc.q may be released, each setting the API version back to "wip" in the first API update PR and evolving the rc number with each following pre-release (rx.m+1 - rx.n).
• When the API version is ready for public release, create the release PR that sets the public API version to 1.1.0. (this PR minimally removes the rc extensions from the version and URL fields in the API yaml file and assures all API release assets are available as per the API readiness checklist).
• After release PR approval, create the release rx.n+1 and publish it on the API release tracker.
• The approved public API version 1.1.0 will be included in the meta-release as planned.

API release numbering

API release numbers are GitHub tags of the format "rx.y".

The release numbers shall follow the guidelines described below.

• Release numbers start with x=1 and y=1: r1.1.
• y is incremented by 1 at each subsequent (pre-)release (for alpha, release-candidate and public API versions), and for a maintenance release, e.g. rx.y+1.
• After a meta-release of a public API version release rx.y, the next release number for this API is rx+1.1 (y resets to 1).
• In case of maintenance of a release rx.y, the next release shall be rx.y+1.
• A maintenance release replaces the previous release in the meta-release.

The following table illustrates the continuous release numbering of an API version across the API release process.

API readiness checklist

To release an API version, an API Sub Project needs to provide the required release assets as specified in the API Readiness Checklist (see description below).

The template for the checklist is the API-Readiness-Checklist.md file located in the CAMARA / ReleaseManagement / documentation repository.

For the readiness of a given API version, an API Sub Project needs to

• copy the API-Readiness-Checklist.md file(s) to the API Sub Project repository in the home/code folder.
• rename the file to include the prefix <API name> plus a dash ("-") e.g. quality-on-demand-API-Readiness-Checklist.md
• provide each release asset as indicated in the column corresponding to the release type
• for an available asset
  • update the Status column with "Y" (yes) if the release asset is available or fulfilled in the current release, or "N" (no) otherwise. Example: an intermediate pre-release may not yet provide all mandatory release assets for the release type.
    
  • update the Comments column with the link to the asset  (if applicable), and any other additional comments as needed

NOTE: the checklists of a release-candidate and the checklist of a subsequent public API version may be the same.

Checklist explanation

The following table explains each of the release assets expected to be delivered in the API release.

Note 1: User Stories are being handled when submitting an API to the API backlog (see here). It is recommended to have at least 2 user stories, which need to be documented by the API Sub Project team. User Stories shall follow the template: Userstory-template.md and be located in the home/documentation/API_documentation folder of the API Sub Project.

Note 2: the addition of a Security review release asset beyond the Commonalities linting rules is for further study.

Readiness checklist per API version

The following table is the API readiness checklist that lists the assets that need to be provided with the API version for it to be ready for its (pre-)release. The required assets depend on 

• the API version type: alpha, release-candidate or public
• for public API versions, in addition, depending on its target status: initial or stable

In the table, 

• "M" indicates a mandatory release asset
• "O" indicates an optional release asset which may be provided with the release, if available.  

The API-Readiness_Checklist.md is available in GitHub for copying to the API Sub projects.

API releases - details 

The GitHub release feature

Technically, an API (pre-)release is created using the GitHub release feature (see Draft/publish a new release). It involves

• A GitHub issue defining the scope of the target API version.
• A release PR associated to this issue.

After release PR approval: 

• a release tag (with the tag name following the API release numbering guidelines above) on the main or on a maintenance release branch.
• a release package containing the API's repository with the corresponding API release assets for each contained API version (zip file). A release package is optional for pre-releases of alpha API versions.

A GitHub release is the combination of a release tag and, optionally, a release package created using the GitHub release feature for an API repository. A GitHub release may not contain any wip APIs versions.

Releasing an API step by step 

This section gives the overview of the steps to release a public version of an API. 

• Create a GitHub issue defining the scope of the API version targeted to be released. Descriptive information in this issue can be reused in the changelog/release notes.
• Create the API release tracker for the targeted public API version as describer here: API release trackers.
• On the main branch, develop the API version scope in a "work-in-progress mode" (API version = wip and version in URL is vwip).
  • several pre-releases for one or more alpha API versions may be created between M1 and M3
• To reach M3, a release PR needs to be created that updates the API to become the first release-candidate API version, including the relevant release assets (see details in section Create the (pre-)release PR below) 
• Further pre-releases of one or more release-candidate API versions may be created between M3 and M4
• To reach M4, a release PR needs to be created that updates the API to become the first public API version, including the relevant release assets (see details in section Create the (pre-)release PR below)
• During above development (M1-M3) and test (M3-M4), make sure to create and record the required release assets according to the API-Readiness-Checklist.
• To release the API, manage the release PR approval, merge the approved release PR and create the release (see below).

NOTE: To be included in the meta-release, the release of the public API version needs to be available.

Prepare the API release

To create a (pre-)release of the API, a release PR (linked to the associated release scope issue) must be created.

A release PR does not change the content the repository other than the following changes:

• the update of the version information in the API OAS definition file(s) within the repository (Info/version field and URL version)
  • no API in the repository shall contain “wip” in the version field in the API OAS definition file
  • at least the version of one API must be changed with respect to the previous release (otherwise there is no sense in doing a release)
• the update of the API-Readiness-Checklist.md for each API in the repository which confirms the availability of all release assets required for the (pre-)release. For details, see the explanations on the API readiness checklist above.
• the update of the Changelog.md in the repository with new content on all APIs at the top for the most recent (pre-)release as follows:
  • for the first alpha or release-candidate API version, all changes since the release of the previous public API version
  • for subsequent alpha or release-candidate API versions, the delta with respect to the previous pre-release
  • for a public API version, the consolidated changes since the release of the previous public API version
• the update of the README.md (as necessary)

Manage the release PR approval

A  release PR has to be approved before the code owner is allowed to merge as follows:

• alpha API versions: by one other code owner (as for any PR)
• release-candidates: by the majority of the API Sub Project Maintainers + one Release Manager
• public API versions:
  • by the majority of the API Sub Project Maintainers (normally given, if the preceding release-candidate was approved), and
  • by the TSC (to be discussed how this will be done formally)
  • the formal approval is based on the review of the release PR for the public API version 
• Approvals shall be documented as reviews in the release PR in GitHub.

Merge the release PR and create the GitHub release

Once approval is obtained, merge the release PR and create the GitHub release: 

• The GitHub release package is (optionally) created using the GitHub release feature.
• The release tag shall be named with the next release number and shall have the following format: rx.y
  • The x.y number shall follow the release numbering scheme as defined in the above section on Release Numbering.
  • Note: Outside the project, the release shall be referred to by the API repository name (for definition see the section on API versioning) followed by the release number e.g. quality-on-demand rx.y
• The release description shall be copied from the CHANGELOG.md (as described above)
• For releases with alpha and release-candidate API versions, tick the "Set as a pre-release" box; for public or maintenance releases, tick "Set as latest release".

Track the release

• Update the API release tracker with the date and tag of the (pre-)release to show progress.

Maintain a public release

An update of a publicly released API needs to be carefully planned. This is especially true for updates that concern breaking changes, but also non-breaking changes, such as new optional functionality. Such updates shall be widely announced and discussed with API consumers.

To update a public API, a next public release of this API needs to be created including the (MAJOR/MINOR/PATCH) update(s).

MAJOR or MINOR updates

Breaking (MAJOR) or non-breaking (MINOR ) updates to a public API version, shall result in a new version of that API in the next meta-release.

For the release of a MAJOR or MINOR update of a publicly released API, the normal API release process (as described above) is applied.

For a MAJOR or MINOR update to a public release rx.y, the next public released is rx+1.n.

PATCH update

A PATCH to a public release is done using a dedicated maintenance branch.

For a PATCH update to a public release rx.y, the next released is rx.y+1. The new public API version will be vx.y.z+1

A shorter release process is applied as follows:

• An API tracker shall be created for teh maintenance version of the API (x.y.z+1)
• A dedicated maintenance branch shall be opened to develop the PATCH of the API
  • the branch name shall be maintenance-rx.y where rx.y is the release number of the public release rx.y being patched
  • Subsequent patches shall be done on the same maintenance branch, and will increase the y number
• The changes are proposed as usual through Issues, PRs, and commits to this maintenance branch (using wip version)
• It is assumed that no intermediate pre-releases are created, however, if needed for the development of the patch; this can be done and should be tracked on the release tracker as usual.
• After all changes are done, a release PR for the patched public API version shall be created and approved.
• After approval, the maintenance release is created for the new public API version x.y.z+1 (per semver 2.0.0) and release number rx.y+1.
• This maintenance release replaces the existing public release of the API in the meta-release.
• The API tracker shall be updated with the new release tag link.
• The PATCH delivered through a maintenance release shall also be merged into a next MAJOR or MINOR API release on the main branch.
• The maintenance branch shall continue to exist for further PATCH updates of the public API version x.y.z+1 (incrementing z) as long as needed.

NOTE: a PATCH is the only case for which a separate branch is created and maintained in the API repository (as pull requests should be prepared within forks of the API repository, c.f. Governance/CONTRIBUTING.md)

Multiple APIs in one release

Although it is highly recommended to develop each API in its own API Sub Project, an API Sub Project may contain multiple, closely related APIs. Because a release concerns the whole API repository, this will result in releasing multiple APIs in one release. In this case, an API version can only be released if all contained APIs provide the required set of public release assets. The API release must not contain any API with a wip version.

In all cases, each API version shall have its own release tracker (under the Sub Project's API Release Tracking page), and, in this case of multiple APIs in the same release, the same release tag will appear in multiple API release trackers.

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.

For API versions with x>0, the next API version number is defined and does NOT change during API development and release preparation. Only the API version extensions and their numbers may change. 

To prepare the release of an API version, one or more release-candidate API versions MUST be created as follows:

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

To manage updates of API versions, the semver 2.0 versioning applies to the API version number as follows:

• changes in the major number when creating non-backward compatible / breaking changes to the API
• changes in the minor number when creating backward compatible changes to the API
• changes in the patch number when correcting an error of the API

During the development of an API version update, all pre-release API versions need to get a version extension so its release can be managed properly.

Example for a backward-compatible update of a public-release API version 1.0.0, resulting in API version 1.1.0:

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

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)

API release checklist

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

The following table identifies the items 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 item

...

alpha

...

release-candidate

...

public-release

...

1

...

API definition

...

Y

...

Y

...

Y

...

2

...

Test results proving API alignment with Commonalities and ICM guidelines

...

Y

...

Y

...

Y

...

3

...

API documentation

...

Y

...

Y

...

Y

...

4

...

User stories

...

Y

...

Y

...

Y

...

5

...

API test cases and documentation

...

N

...

Y

...

Y

...

Test results (API test cases passed)

...

N

...

Y

...

Y

...

7

...

API reference implementation

...

N

...

N

...

N

...

8

...

Tested in at least 2 operator implementations

...

N

...

N

...

N

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

...

Nr

...

API version asset

...

alpha

...

release-candidate

...

public-release

...

8

...

API version tag

...

Y

...

Y

...

Y

...

9

...

API version release package with release notes & tag

...

optional

...

Y

...

Y

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 extension 

...

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

...

API version extension

...

Patch update of API version

...

API version extension

...

Major update of API version

...

API version extension

...