Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

TermDefinition

release

The release of an API version consists in the creation of a GitHub release of the API's repository, with a release tag and (optionally for alpha) a release package. A release can be created for any alpha, release-candidate or public API version. No releases can be created for wip API versions.

pre-release

The term pre-release is used to refer to the release of any of the alpha or release-candidate API versions.

NOTE: all pre-releases are publicly available in the CAMARA GitHub and can be used AT THE USER'S OWN RISK, as changes may happen to such API versions without notice.

alpha release

The term alpha release is used to refer to the release of an alpha API version.

release candidate

The term release candidate is used to refer to the release of a release-candidate API version.

public release

The term public release is used to refer to the release of a public API version. It can have the status initial or stable.

initial public - release

An initial public release only exists for new APIs. It concerns the release of public APIs versions with x = 0 (0.y.z without version extension).

A public release is called "initial" to indicate that the API version has not yet reached full maturity, but is considered stable enough to  be proposed for use in commercial applications. However, the user shall be informed that subsequent API versions may require code changes to their applications.

Initial public releases can be

  • released at any time (outside the meta-release process) in order to allow for rapid evolution of APIs.
  • published as part of a meta-release, after which it is expected that in the next meta-release this API version becomes stable.

stable public - release

A stable public release concerns an API version released after its stability has been demonstrated through 

Stable public releases concern the API versions 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

A meta-release is a set of public of API versions released at a given point in time (Spring and Fall).

All API versions of a given meta-release shall be aligned to the public releases of the Commonalities and Identity and Consent Management (ICM) documentation included in that same meta-release.

maintenance release

The term maintenance release is used to refer to the release of a patch update of a released public API version.

release tag

A release tag is a GitHub tag placed on the main or a maintenance branch that identifies a release of the API version's repository.
release packageA release package is a zip file of the repository created using the GitHub release mechanism together with the release tag. It contains a snapshot of the full API Sub Project repository with the content indicated by the release tag.
API release trackerAn API release tracker is a page that provides the visibility on the progress of the release of a given API version. Each API version under release by an API Sub Project shall have its tracker under their API Sub Project's API Release Tracking page.

...

Info

Initial public releases can be

  • released and published at any time (outside the meta-release process) in order to allow for rapid evolution of APIs.
  • published as part of a meta-release
    •  in this case, it is expected that in the next meta-release this public API version becomes stable.

...

  • A GitHub issue for the release.
  • A "release PR" associated to this issue.
  • If required (see table below), a GitHub release package (zip file of the whole API Sub Project repository).
  • A GitHub release tag with the release name number "rx.y" (see below).

Example of the use of the API release process

For To release a MINOR update of a publicly released API version 1.0.0, resulting in a new the public release for of API version 1.1.0:

  • Develop the 1.1.0 update on the main branch. The first PR updates the version to wip, and the URL to contain vwip.
  • Once sufficiently stable, create an alpha release PR that sets the API version to 1.1.0-alpha.1 and will create release rx.1.
  • Several alpha API versions may be released, each setting the API version back to "wip" in the first API update PR (rx.2 - rx.m)
  • Then (at least) one (or more) release-candidate API versions may be created and released (rx.m+1 - rx.n) 
  • The last release-candidate API version will be proposed for public release. 
  • For meta-release approval, create the public release PR for the next public API version 1.1.0.
  • After meta-release approval, create the release for the new public API version 1.1.0, with its release tag rx.n+1 and release package ("latest")).

...

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

release nametypeAPI version

release number (tag)

release package

release package tag
N/Awork-in-progressN/AN/AN/A
alpha releasealpha

rx.1 ... rx.m

optional

optional: "pre-release"
release candidaterelease-candidate

rx.m+1 ... rx.n

mandatory"pre-release"
public releasepublicrx.n+1mandatory"latest"
maintenance releasepublicrx.n+2 ... rx.n+pmandatory"latest"

...

  • 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 (alpha, release-candidate, initial public release or stable public release)
  • 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 alpha release or release candidate 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 (final) release candidate of an API version and the checklist of its subsequent public release are the same, while additional release assets are required for a subsequent stable public release of the API version.

...

Checklist explanation

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

...

NOTE: a PATCH is the only case for which a separate branch is created and maintained in the API Sub Project (not counting working branches).

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

...