Page Comparison

The API Release Process describes the creation of (pre-)releases of API versions throughout the API lifecycle, and for a given meta-release.

...

...

• at M3: the release-candidate API version implementing the defined API scope for the release (achieved through one or more alpha releases), agreed stable for implementation and functional testing and aligned to the alpha releases with the release-candidate versions of Commonalities and ICM (M1).
• at M4: the final release-candidate public API version ready for the meta-release approval, aligned to the final release candidates with the public versions of Commonalities and ICM (M2), input to subsequent public release.

An API Sub Project can create as many wip, alpha and release-candidate API versions as needed for API development and testing.

...

• a pre-release may be created for any alpha API version. 
• a pre-release must be created for each release-candidate API version.
• a release must be created for each public API version.

...

• For M4, the release PR is prepared. It concerns the public API version and all its public release assets in line with the target maturity status of the API version: initial or stable.
• If Once the PR is approved, the API version will be included in the meta-release.
• Inclusion in the meta-release is done by updating the API release tracker with the date and tag of the resulting GitHub release package.

A subsequent release of a public API version is introduced if/when there are updates to the released API (major/minor/patch).

...

When planning to deliver a public API version into a meta-release, the API Sub Project needs to participate in the meta-release process as described here: Meta-release Process.

To In addition, to be part of a meta-release, 

• the expected alpha, release-candidate and public API versions need to be (pre-)released
• minimally an initial public API version needs to be released
• each (pre-)release must provide 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, a (pre-)release is created using the GitHub features and require:

• A GitHub issue for the release.
• A "pre-release PR" or "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 number "rx.y" (see below).

Example of the use of the API release process

...

• 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 a pre-release PR that sets the API version to 1.1.0-alpha.1 and will create pre-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 must be created and pre-released (rx.m+1 - rx.n) 
• When the release-candidate API version is ready for publication, create the release PR for the next public API version 1.1.0. (this PR minimally removes the -rc.n from the version fields in the API yaml file and assures all API release assets are available as per the API readiness checklist) 
• For the meta-release, approval of the release PR is needed.
• 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")).

...

• 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 the latest pre-release and the checklist of a subsequent release are the same, while additional release assets are required for a subsequent release of the  public API version.

Checklist explanation

• .

Checklist explanation

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

...

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 assets that need to be provided with the API version for it to be ready for its (pre-)release. The required assets depend on 

...

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

...

• 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 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).
  • pre-releases for one or more alpha API versions may be created between M1 and M3
• For M3, the pre-release PR is created which contains the first release-candidate API version (see details in section Create the (pre-)release PR below) 
  • pre-releases for one or more release-candidate API versions may be created between M3 and M4
• For M4, the release PR is created which contains the first public API version (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.
• Manage the "(pre-)release PR " approval, merge the approved "(pre-)release PR " and create the release .
  • The supporting GitHub release is 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.
  • 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

NOTE: To be proposed for meta-release, a release PR needs to be available and approved.

Create the (pre-)release PR

...

• (see below).

NOTE: To be proposed for meta-release, a release PR for a public API version needs to be available and approved.

Create the (pre-)release PR

To create a (pre-)release of the API's repository, first a "(pre-)release PR" (linked to the associated PR issue) must be created.

A “ (pre-)release PR” PR does not change the content of what is in the repository. Hence a “a (pre-)release PR” PR provides (only) the following changes:

• the update of the version information in the API OAS definition file(s) within the repository
  • for a (pre-)release PR, no API in the repository shall contain “wip” within the version field in the API OAS definition file
  • at least the version of one API will be changed with respect to the previous release (otherwise there is no sense in doing a release)
• the update of the <API name>-API-Readiness-Checklist.md 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:
  for an alpha API version, the delta with respect to the previous release
  • for the first alpha or release-candidate API version, all changes since the release of the previous public API version
  • for a 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 (pre-)release PR approval

A  “release PR” A  (pre-)release PR has to be approved before the code owner is allowed to merge as follows:

• alpha releasesAPI 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 releasesAPI 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 final release-candidate version of the API used the release PR for the public release PRAPI version 
• Approvals shall be documented on the API release tracker page.

Merge the release PR and create the GitHub release

...

• .

Merge the (pre-)release PR and create the GitHub release

Once approval is obtained, merge the (pre-)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.

...