Merge pull request #9326 from gkurz/draft-release

Only tag and publish the release when it is fully ready

.github/workflows/release.yaml

@@ -6,16 +6,11 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout code
+      - name: Checkout repository
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - name: Get the new release version
-        run: |
-          release_version=$(./tools/packaging/release/release.sh release-version)
-          echo "RELEASE_VERSION=$release_version" >> "$GITHUB_ENV"
-
       - name: Create a new release
         run: |
           ./tools/packaging/release/release.sh create-new-release
@@ -75,7 +70,7 @@ jobs:
           release_version=$(./tools/packaging/release/release.sh release-version)
           echo "KATA_DEPLOY_IMAGE_TAGS=$release_version latest" >> "$GITHUB_ENV"
 
-      - name: Push multi-arch manifest
+      - name: Publish multi-arch manifest on docker.io and quay.io
         run: |
           ./tools/packaging/release/release.sh publish-multiarch-manifest
         env:
@@ -85,51 +80,56 @@ jobs:
     needs: [build-and-push-assets-amd64, build-and-push-assets-arm64, build-and-push-assets-s390x, build-and-push-assets-ppc64le]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v4
 
       - name: Set KATA_STATIC_TARBALL env var
         run: |
           tarball=$(pwd)/kata-static.tar.xz
           echo "KATA_STATIC_TARBALL=${tarball}" >> "$GITHUB_ENV"
 
-      - name: download-artifacts-amd64
+      - name: Download amd64 artifacts
         uses: actions/download-artifact@v3
         with:
           name: kata-static-tarball-amd64
-      - name: push amd64 static tarball to github
+
+      - name: Upload amd64 static tarball to GitHub
         run: |
           ./tools/packaging/release/release.sh upload-kata-static-tarball
         env:
           GH_TOKEN: ${{ github.token }}
           ARCHITECTURE: amd64
 
-      - name: download-artifacts-arm64
+      - name: Download arm64 artifacts
         uses: actions/download-artifact@v3
         with:
           name: kata-static-tarball-arm64
-      - name: push arm64 static tarball to github
+
+      - name: Upload arm64 static tarball to GitHub
         run: |
           ./tools/packaging/release/release.sh upload-kata-static-tarball
         env:
           GH_TOKEN: ${{ github.token }}
           ARCHITECTURE: arm64
 
-      - name: download-artifacts-s390x
+      - name: Download s390x artifacts
         uses: actions/download-artifact@v3
         with:
           name: kata-static-tarball-s390x
-      - name: push s390x static tarball to github
+
+      - name: Upload s390x static tarball to GitHub
         run: |
           ./tools/packaging/release/release.sh upload-kata-static-tarball
         env:
           GH_TOKEN: ${{ github.token }}
           ARCHITECTURE: s390x
 
-      - name: download-artifacts-ppc64le
+      - name: Download ppc64le artifacts
         uses: actions/download-artifact@v3
         with:
           name: kata-static-tarball-ppc64le
-      - name: push ppc64le static tarball to github
+
+      - name: Upload ppc64le static tarball to GitHub
         run: |
           ./tools/packaging/release/release.sh upload-kata-static-tarball
         env:
@@ -140,8 +140,10 @@ jobs:
     needs: release
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
-      - name: upload versions.yaml
+        uses: actions/checkout@v4
+
+      - name: Upload versions.yaml to GitHub
         run: |
           ./tools/packaging/release/release.sh upload-versions-yaml-file
         env:
@@ -151,8 +153,10 @@ jobs:
     needs: release
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
-      - name: generate-and-upload-tarball
+        uses: actions/checkout@v4
+
+      - name: Generate and upload vendored code tarball
         run: |
           ./tools/packaging/release/release.sh upload-vendored-code-tarball
         env:
@@ -162,9 +166,24 @@ jobs:
     needs: release
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
-      - name: download-and-upload-tarball
+        uses: actions/checkout@v4
+
+      - name: Download libseccomp tarball and upload it to GitHub
         run: |
           ./tools/packaging/release/release.sh upload-libseccomp-tarball
         env:
           GH_TOKEN: ${{ github.token }}
+
+  publish-release:
+    needs: [ build-and-push-assets-amd64, build-and-push-assets-arm64, build-and-push-assets-s390x, build-and-push-assets-ppc64le, publish-multi-arch-images, upload-multi-arch-static-tarball, upload-versions-yaml, upload-cargo-vendored-tarball, upload-libseccomp-tarball ]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Publish a release
+        run: |
+          ./tools/packaging/release/release.sh publish-release
+        env:
+          GH_TOKEN: ${{ github.token }}

docs/Developer-Guide.md

@@ -29,7 +29,7 @@ to build the Kata Containers components from source.
 >
 > If you decide to build from sources, you should be aware of the
 > implications of using an unpackaged system which will not be automatically
-> updated as new [releases](Stable-Branch-Strategy.md) are made available.
+> updated as new [releases](https://github.com/kata-containers/kata-containers/releases) are made available.
 
 You need to install the following to build Kata Containers components:
 

docs/README.md

@@ -69,7 +69,6 @@ Documents that help to understand and contribute to Kata Containers.
 
 ### The Release Process
 
-* [Release strategy](Stable-Branch-Strategy.md)
 * [Release Process](Release-Process.md)
 
 ## Presentations

docs/Release-Process.md

@@ -5,6 +5,27 @@ This document lists the tasks required to create a Kata Release.
 
 - GitHub permissions to run workflows.
 
+## Versioning
+
+The Kata Containers project uses [semantic versioning](http://semver.org/) for all releases.
+Semantic versions are comprised of three fields in the form:
+
+```
+MAJOR.MINOR.PATCH
+```
+
+When `MINOR` increases, the new release adds **new features** but *without changing the existing behavior*.
+
+When `MAJOR` increases, the new release adds **new features, bug fixes, or
+both** and which **changes the behavior from the previous release** (incompatible with previous releases).
+
+A major release will also likely require a change of the container manager version used,
+-for example Containerd or CRI-O. Please refer to the release notes for further details.
+
+**Important** : the Kata Containers project doesn't have stable branches (see
+[this issue](https://github.com/kata-containers/kata-containers/issues/9064) for details).
+Bug fixes are released as part of `MINOR` or `MAJOR` releases only. `PATCH` is always `0`.
+
 ## Release Process
 
 ### Bump the `VERSION` file
@@ -21,7 +42,9 @@ release artifacts.
 
 The action is manually triggered and is responsible for generating a new
 release (including a new tag), pushing those to the
-`kata-containers/kata-containers` repository.
+`kata-containers/kata-containers` repository. The new release is initially
+created as a draft. It is promoted to an official release when the whole
+workflow has completed successfully.
 
 Check the [actions status
 page](https://github.com/kata-containers/kata-containers/actions) to verify all
@@ -29,6 +52,13 @@ steps in the actions workflow have completed successfully. On success, a static
 tarball containing Kata release artifacts will be uploaded to the [Release
 page](https://github.com/kata-containers/kata-containers/releases).
 
+If the workflow fails because of some external environmental causes, e.g. network
+timeout, simply re-run the failed jobs until they eventually succeed.
+
+If for some reason you need to cancel the workflow or re-run it entirely, go first
+to the [Release page](https://github.com/kata-containers/kata-containers/releases) and
+delete the draft release from the previous run.
+
 ### Improve the release notes
 
 Release notes are auto-generated by the GitHub CLI tool used as part of our

docs/Stable-Branch-Strategy.md

@@ -1,151 +0,0 @@
-Branch and release maintenance for the Kata Containers project.
-
-## Introduction 
-
-This document provides details about Kata Containers releases.
-
-## Versioning
-
-The Kata Containers project uses [semantic versioning](http://semver.org/) for all releases. 
-Semantic versions are comprised of three fields in the form:
-
-```
-MAJOR.MINOR.PATCH
-```
-
-For examples: `1.0.0`, `1.0.0-rc.5`, and `99.123.77+foo.bar.baz.5`.
-
-Semantic versioning is used since the version number is able to convey clear 
-information about how a new version relates to the previous version. 
-For example, semantic versioning can also provide assurances to allow users to know 
-when they must upgrade compared with when they might want to upgrade:
-
-- When `PATCH` increases, the new release contains important **security fixes**
-  and an upgrade is recommended.
-
-  The patch field can contain extra details after the number. 
-Dashes denote pre-release versions. `1.0.0-rc.5` in the example denotes the fifth release
- candidate for release `1.0.0`. Plus signs denote other details. In our example, `+foo.bar.baz.5` 
-provides additional information regarding release `99.123.77` in the previous example.
-
-- When `MINOR` increases, the new release adds **new features** but *without
-  changing the existing behavior*.
-
-- When `MAJOR` increases, the new release adds **new features, bug fixes, or
-  both** and which **changes the behavior from the previous release** (incompatible with previous releases).
-
-  A major release will also likely require a change of the container manager version used, 
-for example Containerd or CRI-O. Please refer to the release notes for further details.
-
-## Release Strategy
-
-Any new features added since the last release will be available in the next minor
-release. These will include bug fixes as well. To facilitate a stable user environment, 
-Kata provides stable branch-based releases and a main branch release.
-
-## Stable branch patch criteria
-
-No new features should be introduced to stable branches.  This is intended to limit risk to users,
-providing only bug and security fixes.
-
-## Branch Management
-Kata Containers will maintain **one** stable release branch, in addition to the main branch, for
-each active major release.
-Once a new MAJOR or MINOR release is created from main, a new stable branch is created for
-the prior MAJOR or MINOR release and the previous stable branch is no longer maintained. End of
-maintenance for a branch is announced on the Kata Containers mailing list.  Users can determine
-the version currently installed by running `kata-runtime kata-env`. It is recommended to use the
-latest stable branch available.
-
-A couple of examples follow to help clarify this process.
-
-### New bug fix introduced
-
-A bug fix is submitted against the runtime which does not introduce new inter-component dependencies.
-This fix is applied to both the main and stable branches, and there is no need to create a new
-stable branch.
-
-| Branch | Original version | New version |
-|--|--|--|
-| `main` | `2.3.0-rc0` | `2.3.0-rc1` |
-| `stable-2.2` | `2.2.0` | `2.2.1` |
-| `stable-2.1` | (unmaintained) | (unmaintained) |
-
-
-### New release made feature or change adding new inter-component dependency
-
-A new feature is introduced, which adds a new inter-component dependency. In this case a new stable
-branch is created (stable-2.3) starting from main and the previous stable branch (stable-2.2)
-is dropped from maintenance.
-
-
-| Branch | Original version | New version |
-|--|--|--|
-| `main` | `2.3.0-rc1` | `2.3.0` |
-| `stable-2.3` | N/A| `2.3.0` |
-| `stable-2.2` | `2.2.1` | (unmaintained) |
-| `stable-2.1` | (unmaintained) | (unmaintained) |
-
-Note, the stable-2.2 branch will still exist with tag 2.2.1, but under current plans it is
-not maintained further. The next tag applied to main will be 2.4.0-alpha0. We would then
-create a couple of alpha releases gathering features targeted for that particular release (in
-this case 2.4.0), followed by a release candidate. The release candidate marks a feature freeze.
-A new stable branch is created for the release candidate. Only bug fixes and any security issues
-are added to the branch going forward until release 2.4.0 is made.
-   
-## Backporting Process 
-
-Development that occurs against the main branch and applicable code commits should also be submitted
-against the stable branches. Some guidelines for this process follow::
-  1. Only bug and security fixes which do not introduce inter-component dependencies are
- candidates for stable branches. These PRs should be marked with "bug" in GitHub.
-  2. Once a PR is created against main which meets requirement of (1), a comparable one
- should also be submitted against the stable branches. It is the responsibility of the submitter
- to apply their pull request against stable, and it is the responsibility of the
- reviewers to help identify stable-candidate pull requests.
- 
-## Continuous Integration Testing
-
-The test repository is forked to create stable branches from main. Full CI
-runs on each stable and main PR using its respective tests repository branch.
-
-### An alternative method for CI testing:
-
-Ideally, the continuous integration infrastructure will run the same test suite on both main
-and the stable branches.  When tests are modified or new feature tests are introduced, explicit
-logic should exist within the testing CI to make sure only applicable tests are executed against
-stable and main. While this is not in place currently, it should be considered in the long term.
-
-## Release Management
-
-### Patch releases
-
-Releases are made every four weeks, which include a GitHub release as
-well as binary packages. These patch releases are made for both stable branches, and a "release candidate"
-for the next `MAJOR` or `MINOR` is created from main. If there are no changes across all the repositories, no
-release is created and an announcement is made on the developer mailing list to highlight this.
-If a release is being made, each repository is tagged for this release, regardless
-of whether changes are introduced. The release schedule can be seen on the
-[release rotation wiki page](https://github.com/kata-containers/community/wiki/Release-Team-Rota).
-
-If there is urgent need for a fix, a patch release will be made outside of the planned schedule.
-
-The process followed for making a release can be found at [Release Process](Release-Process.md).
-
-## Minor releases
-
-###  Frequency
-Minor releases are less frequent in order to provide a more stable baseline for users. They are currently
-running on a sixteen weeks cadence. The release schedule can be seen on the
-[release rotation wiki page](https://github.com/kata-containers/community/wiki/Release-Team-Rota).
-
-### Compatibility
-Kata guarantees compatibility between components that are within one minor release of each other. 
- 
-This is critical for dependencies which cross between host (shimv2 runtime) and
-the guest (hypervisor, rootfs and agent).  For example, consider a cluster with a long-running
-deployment, workload-never-dies, all on Kata version 2.1.3 components. If the operator updates
-the Kata components to the next new minor release (i.e. 2.2.0), we need to guarantee that the 2.2.0
-shimv2 runtime still communicates with 2.1.3 agent within workload-never-dies.
-
-Handling live-update is out of the scope of this document. See this [`kata-runtime` issue](https://github.com/kata-containers/runtime/issues/492) for details.

docs/Upgrading.md

@@ -14,9 +14,6 @@ period of time, once a stable release for Kata Containers 2.x is published,
 Kata Containers 1.x stable users should consider switching to the Kata 2.x
 release.
 
-See the [stable branch strategy documentation](Stable-Branch-Strategy.md) for
-further details.
-
 # Determine current version
 
 To display the current Kata Containers version, run one of the following:

src/runtime/virtcontainers/experimental/README.md

@@ -56,8 +56,6 @@ That depends.
 For the feature that breaks backward compatibility, we usually land it as formal feature in a major version bump(x in x.y.z, e.g. 2.0.0).
 But for a new feature who becomes stable and ready, we can release it formally in any minor version bump.
 
-Check Kata Container [versioning rules](../../../../docs/Stable-Branch-Strategy.md#Versioning).
-
 The experimental feature should state clearly in documentation the rationale for it to be experimental, 
 and when it is expected to be non-experimental,
 so that maintainers can consider to make it formal in right release.

tools/packaging/release/release.sh

@@ -108,14 +108,29 @@ EOF
 
 function _create_new_release()
 {
-	_check_required_env_var "RELEASE_VERSION"
 	_check_required_env_var "GH_TOKEN"
 
+	RELEASE_VERSION="$(_release_version)"
+
 	_create_our_own_notes
 
+	# This automatically creates the ${RELEASE_VERSION} tag in the repo
 	gh release create ${RELEASE_VERSION} \
 		--generate-notes --title "Kata Containers ${RELEASE_VERSION}" \
-		--notes-file "/tmp/our_notes_${RELEASE_VERSION}"
+		--notes-file "/tmp/our_notes_${RELEASE_VERSION}" \
+		--draft
+}
+
+function _publish_release()
+{
+	_check_required_env_var "GH_TOKEN"
+
+	RELEASE_VERSION="$(_release_version)"
+
+	# Make the release live on GitHub
+	gh release edit ${RELEASE_VERSION} \
+		--verify-tag \
+		--draft=false
 }
 
 function _publish_multiarch_manifest()
@@ -202,6 +217,7 @@ function main()
 		upload-versions-yaml-file) _upload_versions_yaml_file ;;
 		upload-vendored-code-tarball) _upload_vendored_code_tarball ;;
 		upload-libseccomp-tarball) _upload_libseccomp_tarball ;;
+		publish-release) _publish_release ;;
 		*) >&2 _die "Invalid argument" ;;
 	esac
 }