# How to do a Kata Containers Release
This document lists the tasks required to create a Kata Release.

## Requirements

- 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

When the `kata-containers/kata-containers` repository is ready for a new release,
first create a PR to set the release in the `VERSION` file and have it merged.

### Check GitHub Actions

We make use of [GitHub actions](https://github.com/features/actions) in the
[release](https://github.com/kata-containers/kata-containers/actions/workflows/release.yaml)
file from the `kata-containers/kata-containers` repository to build and upload
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. 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
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
release workflow.  However, some manual tweaking may still be necessary in
order to highlight the most important features and bug fixes in a specific
release.

With this in mind, please, poke @channel on #kata-dev and people who worked on
the release will be able to contribute to that.

### Announce the release

Publish in [Slack and Kata mailing
list](https://github.com/kata-containers/community#join-us) that new release is
ready.