From 693c9487d414fc51999ce6df4ff13817e8cb5d3f Mon Sep 17 00:00:00 2001 From: Greg Kurz <groug@kaod.org> Date: Wed, 27 Mar 2024 09:26:01 +0100 Subject: [PATCH] docs: Adjust release documentation Most of the content of `docs/Stable-Branch-Strategy.md` got de-facto deprecated by the re-design of the release process described in #9064. Remove this file and all its references in the repo. The `## Versioning` section has some useful information though. It is moved to `docs/Release-Process.md`. The documentation of the `PATCH` field is adapted according to new workflow. Fixes #9064 - part VI Signed-off-by: Greg Kurz <groug@kaod.org> --- docs/Developer-Guide.md | 2 +- docs/README.md | 1 - docs/Release-Process.md | 21 +++ docs/Stable-Branch-Strategy.md | 151 ------------------ docs/Upgrading.md | 3 - .../virtcontainers/experimental/README.md | 2 - 6 files changed, 22 insertions(+), 158 deletions(-) delete mode 100644 docs/Stable-Branch-Strategy.md diff --git a/docs/Developer-Guide.md b/docs/Developer-Guide.md index 34ecaf1a2a..bf95fb8888 100644 --- a/docs/Developer-Guide.md +++ b/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: diff --git a/docs/README.md b/docs/README.md index 96bf2622bd..170e17d1ab 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/Release-Process.md b/docs/Release-Process.md index 04f8b1ed2f..9b90276ac3 100644 --- a/docs/Release-Process.md +++ b/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 diff --git a/docs/Stable-Branch-Strategy.md b/docs/Stable-Branch-Strategy.md deleted file mode 100644 index 416bb087a6..0000000000 --- a/docs/Stable-Branch-Strategy.md +++ /dev/null @@ -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. diff --git a/docs/Upgrading.md b/docs/Upgrading.md index 7345d799f7..189ad6519d 100644 --- a/docs/Upgrading.md +++ b/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: diff --git a/src/runtime/virtcontainers/experimental/README.md b/src/runtime/virtcontainers/experimental/README.md index b126f68442..cc1f3026a4 100644 --- a/src/runtime/virtcontainers/experimental/README.md +++ b/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.