Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

How to create an API release ? 

Getting started

1 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. All discussions wrt to this release shall be handled through this issue.

  • 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:
    • Release numbers start with x=0 and y=1: r0.1.
    • During a given release development, x remains the same and 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.0 (y resets to 0).
    • In case of maintenance of a release rx.y, the new public-release shall be rx.y+1.
    • For more information see: API Release Process#APIreleasenumbering
  • Outside the project the release name shall be the API name (for definition see API versioning#APIname) combined with the release number e.g. qod rx.y

2 Create the API release tracker for the target API version as describer here: API release tracking process.

3 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, make sure to create and record the required release assets as per the API-Readiness-Checklist file

4 Once the appropriate stability is reached and create the release PR. 

Repeat step 3 and 4 with alpha releases up to the M3 milestone and release-candidates from the M3 to the M4 milestone.

Create the release PR

A) To create an API release, first a "release PR" (linked to the associated PR issue) must be created to do a release of the API's repository:

The “release PR” does not change the content of what is in the repository except the following points.

  • The “release PR” provides (only) the following changes:
    • the update of the API version information in the API OAS definition files within the repository
      • 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 having a release)
    • the update of the <API name>-API-Readiness-Checklist.md which confirms the availability of all required release assets as defined for the release type. For details, see the explanations on the API readiness checklist below.
    • the update of the Changelog.md in the repository with new content on the top for each changed API:
      • the delta to the previous release for an alpha API version
      • 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 (if necessary)

Manage the release PR approval

  • A  “release PR” has to be approved before the code owner is allowed to merge as follows:
    • alpha releases: by one other code owner (as for any PR)
    • release-candidates: by the majority of the API Sub Project Maintainers + one Release Manager
    • public-releases:
      • 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)
    • NOTE: a public-release should have a formal approval, the actual review is done based on the release-candidate versions of the APIs.

Merge the release PR and create release

  • Directly after the PR is merged, the release (the release tag and optionally the release package) shall be created using the GitHub release functionality ("Draft/publish a new release")
    • The release description shall be copied from the CHANGELOG.md (as described above)
    • For releases with alpha and release-candidate API versions, use "Set as a pre-release", for public-releases "Set as latest release".
  • No labels