DRAFT FOR REVIEW
The API-Release-Guidelines.md file will be created from the below after the review.
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 a 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.
...
- a pre-release may be created for any an alpha API version.
- a pre-release must be created for each release-candidate API versionsversion.
- a pubic public-release must be created for each public-release an API version when in order to be published as part of a meta-release.
publicPublic-releases can have an initial or stable status:
...
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 here (for below. For more details see also: Meta-release Process):.
To be part of a meta-release, (pre-)releases need to be provided as follows (for more details see sections below):
- the expected (pre-)releases for alpha, release-candidates candidate and public-release API versions need to be (pre-)releasedprovided.
- minimally an initial public-release need needs to be provided for the meta-release.
- each (pre-)release must provide 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
- If required, a 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".
...