mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-06-26 15:32:30 +00:00
Merge pull request #605 from amshinde/update-releases-doc
Update releases documents
This commit is contained in:
GabyCT
GitHub
commit
cc2583abdb
@ -62,9 +62,8 @@ Documents that help to understand and contribute to Kata Containers.
|
||||
|
||||
### The Release Process
|
||||
|
||||
* [Release strategy](Releases.md)
|
||||
* [Release Checklist](Release-Checklist.md)
|
||||
* [Stable branches](Stable-Branch-Strategy.md)
|
||||
* [Release strategy](Stable-Branch-Strategy.md)
|
||||
* [Release Process](Release-Process.md)
|
||||
|
||||
## Help Improving the Documents
|
||||
|
||||
|
||||
@ -1,83 +0,0 @@
|
||||
# Release Checklist
|
||||
|
||||
This document lists the tasks required to create a Kata Release.
|
||||
|
||||
It should be pasted directly into a GitHub issue and each item checked off as it is completed.
|
||||
|
||||
- [ ] Raise PRs to update the `VERSION` file in the following repositories:
|
||||
- [ ] [agent][agent]
|
||||
- [ ] [proxy][proxy]
|
||||
- [ ] [runtime][runtime]
|
||||
- [ ] [shim][shim]
|
||||
- [ ] [throttler][throttler]
|
||||
|
||||
Note that the "phase" element of the project encoded in the version strings needs to match for all components. For example, when a `beta` is released, the version string for *all* components should show `beta`.
|
||||
|
||||
- [ ] Ensure all CI tests pass **for all architectures**.
|
||||
|
||||
- [ ] Get confirmation from metrics CI that performance is within acceptable limits.
|
||||
|
||||
- [ ] Create a **signed and annotated tag** for the new release version for the following repositories:
|
||||
- [ ] [agent][agent]
|
||||
- [ ] [proxy][proxy]
|
||||
- [ ] [runtime][runtime]
|
||||
- [ ] [shim][shim]
|
||||
- [ ] [throttler][throttler]
|
||||
|
||||
This is required by `git describe`.
|
||||
|
||||
- [ ] Generate OBS packages based on `HEAD`:
|
||||
- [ ] [agent][agent]
|
||||
- [ ] [guest kernel][kernel]
|
||||
- [ ] [image][image]
|
||||
- [ ] [initrd][initrd]
|
||||
- [ ] [proxy][proxy]
|
||||
- [ ] [`qemu-lite`][qemu-lite]
|
||||
- [ ] [runtime][runtime]
|
||||
- [ ] [shim][shim]
|
||||
- [ ] [throttler][throttler]
|
||||
|
||||
- [ ] Generate snap packages based on `HEAD`
|
||||
- [ ] Push snap packages via snapcraft tool
|
||||
- [ ] Publish snap packages in the snapcraft store
|
||||
|
||||
- [ ] Installation tests (must be done for major releases):
|
||||
- [ ] CentOS
|
||||
- [ ] Fedora
|
||||
- [ ] Ubuntu
|
||||
|
||||
- [ ] Check if any of the following need to be updated:
|
||||
- [ ] Architecture document
|
||||
- [ ] [Developer guide](https://github.com/kata-containers/documentation/blob/master/Developer-Guide.md)
|
||||
- [ ] Installation documentation
|
||||
- [ ] [Limitations document](https://github.com/kata-containers/documentation/blob/master/Limitations.md)
|
||||
|
||||
- [ ] Write release notes:
|
||||
- [ ] Link to Limitations document.
|
||||
- [ ] Brief summary of known issues (with links to appropriate Issues/PRs) for any late-breaking issues.
|
||||
- [ ] List new features.
|
||||
- [ ] List resolved bugs and limitations.
|
||||
- [ ] Version of Docker (ideally range of versions, or "up to version X") supported by the release.
|
||||
- [ ] CRI-O version.
|
||||
- [ ] `cri-containerd` version.
|
||||
- [ ] Version of the OCI spec (ideally range of versions, or "up to version X") supported by the release.
|
||||
- [ ] Version of image used by the release (guest kernel version, guest O/S version, and agent version).
|
||||
- [ ] Add links to Installation instructions.
|
||||
- [ ] Document any common vulnerabilities and exposures (CVEs) fixed with links to the CVE database.
|
||||
|
||||
- [ ] Post release details on the public mailing list and Slack.
|
||||
|
||||
- [ ] Update public IRC channel with a link to the latest release.
|
||||
|
||||
- [ ] Arrange communication of the release through other social media channels.
|
||||
|
||||
[agent]: https://github.com/kata-containers/agent
|
||||
[image]: https://github.com/kata-containers/osbuilder/tree/master/image-builder
|
||||
[initrd]: https://github.com/kata-containers/osbuilder/tree/master/initrd-builder
|
||||
[kernel]: https://github.com/kata-containers/linux
|
||||
[proxy]: https://github.com/kata-containers/proxy
|
||||
[qemu-lite]: https://github.com/kata-containers/qemu
|
||||
[runtime]: https://github.com/kata-containers/runtime
|
||||
[shim]: https://github.com/kata-containers/shim
|
||||
[tests]: https://github.com/kata-containers/tests
|
||||
[throttler]: https://github.com/kata-containers/ksm-throttler
|
||||
107
Release-Process.md
Normal file
107
Release-Process.md
Normal file
@ -0,0 +1,107 @@
|
||||
|
||||
# How to do a Kata Containers Release
|
||||
This document lists the tasks required to create a Kata Release.
|
||||
|
||||
<!-- TOC START min:1 max:3 link:true asterisk:false update:true -->
|
||||
- [How to do a Kata Containers Release](#how-to-do-a-kata-containers-release)
|
||||
- [Requirements](#requirements)
|
||||
- [Release Process](#release-process)
|
||||
- [Bump all Kata repositories](#bump-all-kata-repositories)
|
||||
- [Merge all bump version Pull requests](#merge-all-bump-version-pull-requests)
|
||||
- [Tag all Kata repositories](#tag-all-kata-repositories)
|
||||
- [Check Git-hub Actions](#check-git-hub-actions)
|
||||
- [Create OBS Packages](#create-obs-packages)
|
||||
- [Create release notes](#create-release-notes)
|
||||
- [Announce the release](#announce-the-release)
|
||||
<!-- TOC END -->
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
- [hub](https://github.com/github/hub)
|
||||
|
||||
- OBS account with permissions on [`/home:katacontainers`](https://build.opensuse.org/project/subprojects/home:katacontainers)
|
||||
|
||||
- GitHub permissions to push tags and create releases in Kata repositories.
|
||||
|
||||
- GPG configured to sign git tags. https://help.github.com/articles/generating-a-new-gpg-key/
|
||||
|
||||
- You should configure your GitHub to use your ssh keys (to push to branches). See https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/.
|
||||
* As an alternative, configure hub to push and fork with HTTPS, `git config --global hub.protocol https` (Not tested yet) *
|
||||
|
||||
## Release Process
|
||||
|
||||
### Bump all Kata repositories
|
||||
|
||||
- We have set up a Jenkins job to bump the version in the `VERSION` file in all Kata repositories. Go to the [Jenkins bump-job page](http://jenkins.katacontainers.io/job/release/build) to trigger a new job.
|
||||
- Start a new job with variables for the job passed as:
|
||||
- `BRANCH=<the-branch-you-want-to-bump>`
|
||||
- `NEW_VERSION=<the-new-kata-version>`
|
||||
|
||||
For example, in the case where you want to make a patch release `1.10.2`, the variable `NEW_VERSION` should be `1.10.2` and `BRANCH` should point to `stable-1.10`. In case of an alpha or release candidate release, `BRANCH` should point to `master` branch.
|
||||
|
||||
Alternatively, you can also bump the repositories using a script in the Kata packaging repo
|
||||
```
|
||||
$ cd ${GOPATH}/src/github.com/kata-containers/packaging/release
|
||||
$ export NEW_VERSION=<the-new-kata-version>
|
||||
$ export BRANCH=<the-branch-you-want-to-bump>
|
||||
$ ./update-repository-version.sh -p "$NEW_VERSION" "$BRANCH"
|
||||
```
|
||||
|
||||
### Merge all bump version Pull requests
|
||||
|
||||
- The above step will create a GitHub pull request in the Kata projects. Trigger the CI using `/test` command on each bump Pull request.
|
||||
- Check any failures and fix if needed.
|
||||
- Work with the Kata approvers to verify that the CI works and the pull requests are merged.
|
||||
|
||||
### Tag all Kata repositories
|
||||
|
||||
Once all the pull requests to bump versions in all Kata repositories are merged,
|
||||
tag all the repositories as shown below.
|
||||
```
|
||||
$ cd ${GOPATH}/src/github.com/kata-containers/packaging/release
|
||||
$ git checkout <kata-branch-to-release>
|
||||
$ git pull
|
||||
$ ./tag_repos.sh -p -b "$BRANCH" tag
|
||||
```
|
||||
|
||||
### Check Git-hub Actions
|
||||
|
||||
We make use of [GitHub actions](https://github.com/features/actions) in this [file](https://github.com/kata-containers/kata-containers/blob/master/.github/workflows/main.yaml) in the `kata-containers/kata-containers` repository to build and upload release artifacts. This action is auto triggered with the above step when a new tag is pushed to the `kata-containers/kata-conatiners` repository.
|
||||
|
||||
Check the [actions status page](https://github.com/kata-containers/kata-containers/actions) to verify all 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/runtime/releases).
|
||||
|
||||
### Create OBS Packages
|
||||
|
||||
- We have set up an [Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/) job
|
||||
to trigger generation of Kata packages in [OBS](https://build.opensuse.org/).
|
||||
Go to the [Azure Pipelines job that creates OBS packages](https://dev.azure.com/kata-containers/release-process/_release?_a=releases&view=mine&definitionId=1).
|
||||
- Click on "Create release" (blue button, at top right corner).
|
||||
It should prompt you for variables to be passed to the release job. They should look like:
|
||||
|
||||
```
|
||||
BRANCH="the-kata-branch-that-is-release"
|
||||
BUILD_HEAD=false
|
||||
OBS_BRANCH="the-kata-branch-that-is-release"
|
||||
```
|
||||
The above step shall create OBS packages for Kata for various distributions that Kata supports and test them as well.
|
||||
- Verify that the packages have built successfully by checking the [Kata OBS project page](https://build.opensuse.org/project/subprojects/home:katacontainers).
|
||||
|
||||
### Create release notes
|
||||
|
||||
We have a script in place in the packaging repository to create release notes that include a short-log of the commits across Kata components.
|
||||
|
||||
Run the script as shown below:
|
||||
|
||||
```
|
||||
$ cd ${GOPATH}/src/github.com/kata-containers/packaging/release
|
||||
# Note: OLD_VERSION is where the script should start to get changes.
|
||||
$ ./runtime-release-notes.sh ${OLD_VERSION} ${NEW_VERSION} > notes.md
|
||||
# Edit the `notes.md` file to review and make any changes to the release notes.
|
||||
# Add the release notes in GitHub runtime.
|
||||
$ hub -C "${GOPATH}/src/github.com/kata-containers/runtime" release edit -F notes.md "${NEW_VERSION}"
|
||||
```
|
||||
|
||||
### Announce the release
|
||||
|
||||
Publish in [Slack and Kata mailing list](https://github.com/kata-containers/community#join-us) that new release is ready.
|
||||
84
Releases.md
84
Releases.md
@ -1,84 +0,0 @@
|
||||
* [Introduction](#introduction)
|
||||
* [Versioning](#versioning)
|
||||
* [Tagging repositories](#tagging-repositories)
|
||||
* [Components](#components)
|
||||
* [Release checklist](#release-checklist)
|
||||
* [Release process](#release-process)
|
||||
|
||||
## 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 Docker\*. Please refer to the release notes for further details.
|
||||
|
||||
## Tagging repositories
|
||||
|
||||
To create a signed and annotated tag for a repository, first ensure that `git(1)` is configured to use your `gpg(1)` key:
|
||||
|
||||
```
|
||||
$ git config --global user.signingkey $gpg_key_id
|
||||
```
|
||||
|
||||
To create a signed and annotated tag:
|
||||
|
||||
```
|
||||
$ git tag -as $tag
|
||||
```
|
||||
|
||||
The tag name (`$tag` in the previous example) must conform to the [versioning](#versioning) requirements (e.g. `1.0.0-rc2`).
|
||||
|
||||
The annotation text must conform to the usual [patch format rules](https://github.com/kata-containers/community/blob/master/CONTRIBUTING.md#patch-format). Specifically:
|
||||
|
||||
- The subsystem must be "`release: $tag`".
|
||||
- The body of the message must contain details of changes in the release in `git-shortlog(1)` format.
|
||||
|
||||
## Components
|
||||
|
||||
A new release will result in all Kata components being given a new [version](#versioning), even if no changes were made to that component since the last version. The version for a release is **identical** for all components.
|
||||
|
||||
This strategy allows diagnostic tools such as `kata-runtime kata-env` to record full version details of all components to help with problem determination.
|
||||
|
||||
Note that although hypervisor and guest kernel both have versions, these are not updated for new releases as they are not core components developed by the Kata community.
|
||||
|
||||
## Release checklist
|
||||
|
||||
The detailed steps to follow to create a new release are specified in the [Release Checklist](Release-Checklist.md).
|
||||
|
||||
## Release process
|
||||
|
||||
The Release Owner must follow the following process, which is designed to ensure clarity, quality, stability, and auditability of each release:
|
||||
|
||||
- Raise a [new GitHub issue in the `kata-containers` repository](https://github.com/kata-containers/kata-containers/issues/new) and assign to themselves.
|
||||
|
||||
This issue is used to track the progress of the release with maximum visibility.
|
||||
|
||||
- Paste the release checklist into the issue.
|
||||
|
||||
- Follow the instructions in the release Checklist and "check" each box in the issue as they are completed.
|
||||
|
||||
This is useful for tracking so that the stage of the release is visible to all interested parties.
|
||||
|
||||
- Once all steps are complete, close the issue.
|
||||
@ -1,12 +1,47 @@
|
||||
Branch and release maintenance for the Kata Containers project.
|
||||
|
||||
# Overview
|
||||
## Introduction
|
||||
|
||||
As detailed in the [release documentation](https://github.com/kata-containers/documentation/blob/master/Releases.md),
|
||||
the Kata Containers project makes use of semantic versioning. A release version is described
|
||||
by MAJOR.MINOR.PATCH. Early in the project, we will introduce many new features, which require
|
||||
minor version changes as well as bug fixes. To facilitate a stable user environment, Kata will
|
||||
begin to provide stable branch-based releases and a master branch release.
|
||||
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 Docker\*. 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 master branch release.
|
||||
|
||||
## Stable branch patch criteria
|
||||
|
||||
@ -94,6 +129,8 @@ of whether changes are introduced. The release schedule can be seen on the
|
||||
|
||||
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
|
||||
|
||||
@ -108,7 +108,7 @@ Manual installation instructions are available for [these distributions](#suppor
|
||||
>
|
||||
> - Power users who decide to build from sources should be aware of the
|
||||
> implications of using an unpackaged system which will not be automatically
|
||||
> updated as new [releases](../Releases.md) are made available.
|
||||
> updated as new [releases](../Stable-Branch-Strategy.md) are made available.
|
||||
|
||||
[Building from sources](../Developer-Guide.md#initial-setup) allows power users
|
||||
who are comfortable building software from source to use the latest component
|
||||
|
||||
Loading…
Reference in New Issue
Block a user