DRAFT FOR REVIEW
The API-Release-Guidelines.md file will be created from the below after the review.
- the definitions of API version, version extension, API version in URL and API name will be copied to the API-Design-Guidelines.md section 5.
- the definition of the API version types
API version types
work-in-progress (wip) API version
The purpose of a work-in-progress API version is to indicate that the API is unstable due to one or more PRs being committed, possibly resulting in temporary inconsistencies.
- A work in progress (wip) API version has wip instead of x.y.z as version number in the API OAS definition file, and vwip in the URL.
- A wip API version may exist in 2 cases
- during the first introduction of a new API upto the creation of the first alpha API version
- during the time that one or more Pull Requests (PRs) are committed after a given release of an API.
- Between different PR commits, the API version remains "wip".
- After or with the last PR commit, the next API version pre-release is prepared.
- The maintainers of the API decide on the release (or not) of the resulting next API version, implying that its corresponding release assets will be created.
alpha (alpha) API version
The purpose of an alpha API version is to support rapid development of an API and the creation of test implementations for feedback purposes.
- An alpha API version (x.y.z
- An 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.
release-candidate (rc) API version
The purpose of a release-candidate API version is to allow for (only) bug fixing encountered during further API implementation testing.
- A release-candidate API version (x.y.z-rc.n) is a pre-release of an API version which is stabilized and intended to become the next public-release API version.
- It shall be used to create the API test results and other required release assets.
- A release-candidate API version can be proposed for meta-release. In this case, the public-release API version needs to be prepared in a PR
public-release API version
The purpose of a public-release API version is that it can be used by organization outside CAMARA in application development.
- A public-release API version (x.y.z) is a major/minor/patch stable version of an API.
- A public-release API version with x=0 may exist. This API version is considered to be not yet stable, and is referred as an initial API version.
- A public-release API version with x>0 is referred to as a stable API version.
- A public-release API version is published as part of a CAMARA meta-release.
- To be accepted for meta-release, the public-release API version PR needs to go through TSC approval.
initial public-release API version
A public-release API version is called "initial" to indicate that this API version has not yet reached full maturity, but is considered stable enough to have a public-release as part of a meta-release. It is expected that in the next meta-release this API version becomes stable.
- Initial public-release API versions only exist for new APIs. They are API versions with x = 0 (0.y.z without version extension).
- An initial public-release API version, the API version in the URL may also include the y (minor) version number v0.y (with a dot). This is to simplify the testing of different initial public-release API versions.
- In initial public-release API versions, 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 public-release API versions:
An update due to a breaking change in a public-release API version 0.y.z results in a next API version: 0.y+1.0. Example: 0.9.0 → 0.10.0
- An update due to a non-breaking change results in an API version change from 0.y.z to API version 0.y.z+1. Example: 0.9.0 → 0.9.1
- After this, -alpha.m and -rc.n extensions shall again be applied throughout the development of the API towards the updated public-release API version.
Initial public-release API versions can be proposed for use in commercial applications, but the user shall be informed that subsequent API versions may require code changes to their applications.
stable public-release API version
A public-release API version is considered "stable" once it has been deployed by at least 2 operators.
- Stable public-release API versions are API versions released after the stability of the API version has been demonstrated through
- certification of the API in at least 2 commercial contexts
- availability and use of the API in at least 2 commercial deployments.
- Once a first stable public-release API version x.y.z has been created (x > 0), normally no further initial public-release API versions (x = 0) shall exist.
Stable public-release API versions are the ones recommended for use in commercial applications. The user can expect that subsequent API versions will be backward-compatible with the one they are using, unless explicitly announced otherwise.
API version types in the release process
The following table gives the values of the API version (Info object) and the API version in the URL (servers object) used in the release process of the API.
NOTE: for initial API versions (x=0), the API version in the URL is exceptionally allowed to contain both the MAJOR and the MINOR version numbers (0.y).
...
public-release
...
x.y.z
...
v0.y
...
vx
...
Yes
Precedence examples:
- 0.1.0 < 0.2.0-alpha.1 < 0.2.0-alpha.2 < 0.2.0-rc.1 < 0.2.0-rc.2 < 0.2.0 (initial public-release)
- 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 (stable public-release)
- 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 < 3.0.0
Releasing an API step by step
Definitions
| Term | Definition |
|---|---|
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-release 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-release API version. It can have the status initial or stable. |
meta-release | A meta-release is a set of public-releases of API versions made available at a given point in time (Spring and Fall). All API versions of a given meta-release shall be aligned to the Commonalities and Identity and Consent Management (ICM) public-releases included in that same meta-release. |
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 package | A 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 releases
In preparation of the public-release of an API version, an API Sub Project can create as many wip, alpha and release-candidate API versions as needed for API development and testing. The API versioning is done as described in the API versioning guidelines here: API versioning.
The API Sub Project creates a release for an API version as follows:
- a pre-release may be created for an alpha API version.
- a pre-release must be created for each release-candidate API version.
- a public-release must be created for an API version in order to be published as part of a meta-release.
Public-releases can have an initial or stable status:
- an initial public-release indicates that the public-release API version is the result of rapid development and is still unstable, e.g. API versions with a v0.x.y version number.
- a stable public-release indicates that the public-release API version is stable and will be maintained.
When planning to deliver a public-release API version into a meta-release, the API Sub Project needs to participate in the meta-release cycle as described below. For more details see also: Meta-release Process.
To be part of a meta-release, (pre-)releases need to be provided as follows:
- the expected (pre-)releases for alpha, release-candidate and public-release API versions need to be provided.
- minimally an initial public-release needs to be provided for the meta-release.
- each (pre-)release must include the required set of API release assets according to the API readiness checklist described below.
- API (pre-)releases are numbered (tagged) using the API release numbering guideline (see below).
Technically, an API release is created using GitHub features:
- A GitHub issue for the release
- A "release PR" for this issue
- A GitHub release package (zip file of the API Sub Project repository)
- A GitHub release tag with the release name rx.y
API release numbering
API release numbers are GitHub tags of the format "rx.y".
IMPORTANT: Release numbers are not related to the API version.
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 alpha, release-candidate and public-release, and for a maintenance release, e.g. rx.y+1.
- After a meta-release of an API through 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 new public-release shall be rx.y+1.
Example of continuous release numbering across the API version.
| API version | release tag | release package | release package tag |
|---|---|---|---|
| work-in-progress | N/A | N/A | N/A |
| alpha | rx.1 ... rx.m | optional | optional [ "pre-release" ] |
| release-candidate | rx.m+1 ... rx.n | mandatory | "pre-release" |
| public-release | rx.n+1 | mandatory | "latest" |
How to create an API release ?
An API release is created using the GitHub PR and release features and results in:
- a release tag (following the release numbering guidelines below) on the main or on a maintenance release branch, identifying the release of the API version.
- a release package containing the API's repository with the corresponding API release assets for the released API version (zip file). This is optional for alpha releases.
API releases are numbered (tagged) following the API release numbering guidelines (see section above).
Releasing an API step by step
This section gives the overview of the steps to release an API. More details can be found in the API Release Process description.
- Create a GitHub issue defining the scope of the targeted API release. Descriptive information in this issue can be reused in the changelog/release notes
...
- .
- Create the API release tracker for the target API version as describer here: API release
...
- trackers.
- On the main branch, develop the API scope in a "work-in-progress mode" (API version = wip and version in URL is vwip).
- during development and test, make sure to create and record the required release assets according to the API-Readiness-Checklist file
- Once the required stability is reached, create the "release PR"
...
- . The “release PR” provides only the following changes:
- update the version information in the API OAS definition files (no "wip" in any of the API files).
- update of the <API name>-API-Readiness-Checklist.md ensuring all required release assets are available.
- update of the Changelog.md in the repository with new content on the top for each changed API:
- for an alpha API version, the delta to the previous release
- for the first release-candidate, all changes since the last public-release
- for the subsequent release-candidate, only the delta to the previous release candidate
- for the public-release, the consolidated changes since the last public-release
- the update of the README.md (as necessary)
Manage the "release PR" approval, merge the approved "release PR" and create the release
- An API release is created using the GitHub release feature.
- The release name shall be the same as the release tag 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 API release numbering.
- Outside the
...
- API Sub Project, the release name shall be the API name (for definition see
...
- versioning section in the API Design Guidelines) combined with the release number e.g. qod rx.y
Repeat step 3, 4 and 5 for
- alpha releases up to the M3 milestone: rx.1 through rx.m (with first alpha release: r0.1)
- release-candidates between the M3 and the M4 milestone: rx.m+1 through rx.n
- finishing with the public-release for inclusion in the meta-release: rx.n+1
- maintenance-releases (for MINOR and PATCH updates) after public release: rx.n+2 and up
- next release (for MAJOR updates): same as above, starting at rx+1.0
Example moved back to Confluence