diff --git a/documentation/API-Readiness-Checklist.md b/documentation/API-Readiness-Checklist.md index 320f77c..5931778 100644 --- a/documentation/API-Readiness-Checklist.md +++ b/documentation/API-Readiness-Checklist.md @@ -2,7 +2,7 @@ Checklist for api-name api-version in rx.y. -| Nr | API release assets | alpha | release-candidate | public-release
initial | public-release
stable | Status | Comments | +| Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Comments | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| | 1 | API definition | M | M | M | M | | link | | 2 | Design guidelines from Commonalities applied | O | M | M | M | | | @@ -15,13 +15,13 @@ Checklist for api-name api-version in rx.y. | 9 | Test result statement | O | O | O | M | | link | | 10 | API release numbering convention applied | M | M | M | M | | | | 11 | Change log updated | M | M | M | M | | link | -| 12 | Previous public-release was certified | O | O | O | M | | | +| 12 | Previous public release was certified | O | O | O | M | | | To fill the checklist: - in the line above the table, replace the api-name, api-version and the rx.y by their actual values for the current API version and release. -- in the Status column, put "Y" (yes) if the release asset is available or fulfilled in the current release, or "N" (no) otherwise. You can add comments as needed. Example: an intermediate alpha or release-candidate release may not yet provide all mandatory release assets for the release type in an intermedaite release. -- in the Comments column, provide links whenever available to the assests, and any other relevant comments. +- in the Status column, put "Y" (yes) if the release asset is available or fulfilled in the current release, a "N" (no) or a "tbd". Example use of "tbd" is in case an alpha or release-candidate API version does not yet provide all mandatory assets for the release. +- in the Comments column, provide the link to the asset once available, and any other relevant comments. -Note: It is normal that the checklists of the (final) release-candidate and its subsequent public-release are the same, while additional release assets are required for a subsequent stable public-release. +Note: the checklists of a public API version and of its preceding release-candidate API version can be the same. -The documentation for the content of the checklist is here: [API Readiness Checklist documentation](https://wiki.camaraproject.org/x/AgAVAQ#APIReleaseProcess-APIreadinesschecklist) +The documentation for the content of the checklist is here: [API Readiness Checklist](https://wiki.camaraproject.org/x/HQBFAQ) diff --git a/documentation/API_Release_Guidelines.md b/documentation/API_Release_Guidelines.md index 1e67291..5b2dda9 100644 --- a/documentation/API_Release_Guidelines.md +++ b/documentation/API_Release_Guidelines.md @@ -4,59 +4,75 @@ | 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 (*) | -| 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.| -| maintenance-release | The term maintenance-release is used to refer to a patch update of a public-release 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 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 release tracker | An API release tracker is a page that provides the visibility on the progress of the release of a given API version. All API versions released by an API Sub Project shall have a tracker under their API Sub Project's API Release Tracking page. | +| pre-release | A pre-release is a GitHub release of an API repository which contains alpha or release-candidate API versions (*). Note: the term release is also often used here but it should be clear from the context. | +| release | A release is a GitHub release of an API repository which contains public API versions - initial versions (0.y.z) or stable versions (x.y.z with x>=1) . Releases may be proposed as part of a meta-release.| +| meta-release | A meta-release is a set of public API versions across CAMARA, 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.| +| maintenance release | A maintenance release is a Github release of a repository which contains a patch update of a public API version. | +| release tag | A release tag is a Git tag placed on the main or a maintenance branch that identifies a release of the API repository. It is created as part of a GitHub release | +| release package | A release package is a zip file of the GitHub repository created using the GitHub release mechanism. It contains a snapshot of the full API repository content which is marked with the release tag. | +| GitHub release | A GitHub release is the combination of a release tag and, optionally, a release package of the GitHub repository (zip file) created using the GitHub release feature. A GitHub release applies to the full API repository. A GitHub release may contain alpha, release-candidate or public API version(s). A GitHub release shall not include any wip API versions.`| +| release pull request (PR) | A release PR is created within an API repository to prepare its GitHub release. A release PR shall minimally set the version and URL fields in the API yaml file(s) to the exact API version and establish the availability of the API release assets as per the API readiness checklist. | +| API release tracker | An API release tracker provides the visibility on the progress of the (pre-)releases of a given API version within the CAMARA Wiki. Each public API version planned for release by an API Sub Project shall have its release tracker under their API Sub Project's API Release Tracking wiki page. | -(*) 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. +(*) NOTE: pre-releases are not meant to be included in a meta-release. 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. -## API releases +## API releases - overview -In preparation of the public-release of an API version, an API Sub Project can create as many alpha and release-candidate API versions as needed for API development and testing. The API versioning is done as described in the API design guidelines (section on versioning).  +### Release process -The API Sub Project creates a release for an API version as follows: +To prepare the release of a public API version, API versions shall be (pre-)released 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 the an API version in order to be published as part of a meta-release. +* before M3, release (optionally) one or more alpha API versions as needed +* to reach M3, release the first release-candidate API version: + * the release-candidate implements the scope of the target public API version. + * this pre-release is agreed to be ready for API implementation and functional testing. + * it is aligned with the release-candidate versions of Commonalities and ICM +* between M3 and M4, release additional release-candidate API versions as needed +* to reach M4, release the public API version: + * this is the version ready for inclusion in the meta-release (if so planned). + * the public API version must be aligned with the released public version of Commonalities and ICM which shall be available 2 weeks before M4. -Public-releases can have an initial or stable status: +An API Sub Project can release as many alpha and release-candidate API versions as useful for API development and testing. In between (pre-)releases, the API version is set to "wip" (to indicate that this API version should not be used). -* 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. +### Public API versions -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](https://wiki.camaraproject.org/x/G7N3). +Public API versions can have an initial or stable status. -To be part of a meta-release, (pre-)releases need to be provided as follows: + * An initial public API version is the result of rapid development and 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, the milestones defined for the meta-release have to be followed. For more details see also: [Meta-release Process](https://wiki.camaraproject.org/x/G7N3). + * A public API version is released only if it provides all required API readiness checklist items (see: [API Readiness Checklist](https://wiki.camaraproject.org/display/CAM/API+Release+Process#APIReleaseProcess-APIreadinesschecklist)). +* For stable public API versions, participation in the meta-release process is mandatory. As stable API versions are recommended for use in commercial applications, and the user can expect that subsequent public API versions will be backward-compatible, there are additional API readiness checklist items to be provided for the release of stable API versions. -* the expected (pre-)releases for alpha, release-candidate and public-release API versions need to be provided. -* minimally an initial public-release need 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). +### Meta-release -Technically, an API release is created using GitHub features: +To be part of a meta-release, the API Sub Project needs to participate in the meta-release process. For the meta-release, the following needs to be provided: -* A GitHub issue for the release -* A "release PR" associated to this issue -* A GitHub release package (zip file of the API Sub Project repository) -* A GitHub release tag with the release name rx.y +* the API release tracker (see [API release trackers](https://wiki.camaraproject.org/x/HQBFAQ)) +* the expected (pre-)releases at the respective M3 and M4 milestones +* minimally an initial public API version +* the required set of API release assets according to the API readiness checklist (see below). -## API release numbering +## Release guidelines + +### GitHub release  + +Technically, a release of an API repository is created using the GitHub issue, pull request (PR) and release features and requires: + +* A GitHub issue defining the scope of the release of the API version +* A release PR associated to this issue (setting the version and more - see below) +* A GitHub release package (zip file of the whole API repository, including API(s) and release assets) +* A GitHub release tag with the release number "rx.y" following the API release numbering guidelines (see next section). + +### API release numbering --- -**IMPORTANT: Release numbers are not related to the API version.** +**IMPORTANT: Release numbers are NOT related to the API version.** -* **API releases start at r1.1** +* **API release numbers start at r1.1** -* API versioning is described [here](https://wiki.camaraproject.org/x/a4BaAQ). +* API versioning is described in the Commonalities [API-design-guidelines.md](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md) and on the [Release Management wiki](https://wiki.camaraproject.org/x/a4BaAQ). --- @@ -65,68 +81,75 @@ API release numbers are GitHub tags of the format "rx.y". 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. +* 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. +* In case of maintenance of a release rx.y, the new public release shall be rx.y+1. Example of continuous release numbering of an API version across its release types. -| 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" | -| maintenance-release | rx.n+2 ... rx.n+p | mandatory | "latest" | - -## How to create an API release ?  +| Release type | API version | release tag | release package | release package label | +|------|------|:------:|:------:|:------:| +| N/A | work-in-progress | N/A | N/A | N/A | +| pre-release | alpha | rx.1 ... rx.m | optional | optional: "pre-release" | +| pre-release | release-candidate | rx.m+1 ... rx.n | mandatory | "pre-release" | +| release | public | rx.n+1 | mandatory | "latest" | +| maintenance release | public | rx.n+2 ... rx.n+p | mandatory | "latest" | -An API release is created using the GitHub PR and release features and results in: +## Releasing an API step by step -* 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. +This section lists the steps to release an API version. More details can be found here: [API Release Process](https://wiki.camaraproject.org/x/AgAVAQ). -API releases are numbered (tagged) following the API release numbering guidelines (see section above). +**Release preparation** -## Releasing an API step by step +* Create a GitHub issue defining the scope of the targeted API version. Descriptive information in this issue can be reused in the `CHANGELOG.md` file in the release notes part. +* Create the API release tracker for the target API version as described here: [API release trackers](https://wiki.camaraproject.org/x/HQBFAQ). -This section gives the overview of the steps to release an API. More details can be found in the [API Release Process](https://wiki.camaraproject.org/x/AgAVAQ) description. +**API version development** -**Release preparation** +On the main branch, +* develop the API scope in a "work-in-progress mode" (API version = wip and version in URL is vwip). +* make sure to create the required release assets and record them in the `API-Readiness-Checklist.md` file -* 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 tracking process](https://wiki.camaraproject.org/x/HQBFAQ). +**Create the release PR** -**Release development** +Once the defined scope and required stability is reached, create the (pre-)release PR. -* 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.md]() 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 local copy of the [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) * +A (pre-)release PR provides only the following changes:  +* update of the version information in the API OAS definition files (no "wip" in the version field and base URL of any of the API files). +* update the `API-Readiness-Checklist.md` file ensuring all required release assets are available. If this file not yet available, create a local copy under the /documentation folder and prefix it with the respective API name (copy it from [ReleaseManagement/documentation/API-Readiness-Checklist.md](https://github.com/camaraproject/ReleaseManagement/blob/main/documentation/API-Readiness-Checklist.md). +* update the `CHANGELOG.md` file in the home of the API repository. If not yet available, copy it from [ReleaseManagement/documentation/CHANGELOG_TEMPLATE.md](https://github.com/camaraproject/ReleaseManagement/blob/main/documentation/CHANGELOG_TEMPLATE.md). See also the example available there. + * add a new section at the top of the file for the release and each API version with the following content: + * for each first alpha or release-candidate API version, all changes since the release of the previous public API version + * for 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 +* update of the API repository `README.md` file (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 the versioning section in the [API Design Guidelines](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md)) followed by the release number e.g. qod rx.y +**Create the release** +* manage the release PR approval +* merge the approved release PR +* create the release: + * an API release is created using the GitHub release feature (a release tag and, optionally, a release package). + * 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 + * the release description within the GitHub release should be a copy of the section about the release within the CHANGELOG.md +* update the API release tracker with the date and release tag link for the release -**Release process** +**Maintenance release** -Repeat the above release steps for +In case a patch update of a public API version x.y.z is required, the patched public API version x.y.z+1 shall be created through a maintenance release on a separate branch referred to as a maintenance branch. -* alpha releases up to the M3 milestone (at M3 the first release-candidate shall be ready) -* release-candidates between the M3 and the M4 milestone, -* at M4, provide the public-release for inclusion in the meta-release at the M5 milestone +NOTE: a patch is the only case for which a separate branch is created and maintained within the API repository (as pull requests should be prepared within forks of the API repository, c.f. [Governance/CONTRIBUTING.md](https://github.com/camaraproject/Governance/blob/main/CONTRIBUTING.md)) -**Release maintenance** +## Example of the API release process -In case a patch update of a public-release API version x.y.z is required, the patched public-release API version x.y.z+1 shall be created as a maintenance-release on a separate branch referred to as a maintenance branch. +To release a MINOR update of a public API version 1.0.0, resulting in the release of public API version 1.1.0: -NOTE: a patch is the only case for which a separate branch is created and maintained within the API repository (as pull requests should be prepared within forks of the API repository, c.f. https://github.com/camaraproject/Governance/blob/main/CONTRIBUTING.md) +* Develop the 1.1.0 updates on the main branch. The first PR shall update the OAS file setting the API version to wip, and the URL to vwip. +* Once sufficiently stable, create a release PR for the API version 1.1.0-alpha.1. +* After release PR approval, create the pre-release rx.1 and publish it on the API release tracker. +* Additional alpha API versions 1.1.0-alpha.p may be released. For each such alpha API version, set the API version to "wip" in the first API update PR, and only set the next API version in the release PR of the next pre-release. The alpha number evolves with each following pre-release (rx.2 - rx.m). +* When the API version scope development is complete, create a release PR for the release-candidate API version 1.1.0-rc.1 +* Additional release-candidate API versions 1.1.0-rc.q may be released. For each such release-candidate API version, set the API version to "wip" in the first API update PR, and only set the next API version in the release PR of the next pre-release. The rc number evolves with each following pre-release (rx.m+1 - rx.n). +* When the API version is ready for public release, create the release PR that sets the public API version to 1.1.0. (this PR minimally removes the rc extensions from the version and URL fields in the API yaml file and assures all API release assets are available as per the API readiness checklist). +* After release PR approval, create the release rx.n+1 and update the API release tracker. +* The approved public API version 1.1.0 will be included in the meta-release.