linuxkit/docs/releasing.md

Making a LinuxKit release

This document describes the steps to make a LinuxKit release. A LinuxKit release consists of:

• A git tag of the form vX.Y on a specific commit.
• Packages on Docker hub, tagged with the release tag.
• All sample YAML files updated to use the release packages
• linuxkit binaries for all supported architectures.
• Changelog entry

Note, we explicitly do not tag kernel images with LinuxKit release tags as we encourage users to stay current with the kernel releases. We also do not tag test and mkimage packages as these are not end-user facing.

Pre-requisites

Releases can be done by any maintainer. Maintainers need to have access to build machines for all architectures support by LinuxKit and signing keys set up to sign Docker hub images.

Release preparation

The release preparation is by far the most time consuming task as it involves updating all packages and YAML files.

The release preparation is performed on a branch of your up-to-date LinuxKit clone. This document assumes that your clone of the LinuxKit repository is available as the origin remote in your local git clone (in my setup the official LinuxKit repository is available as upstream remote). If your setup is different, you may have to adjust some of the commands below.

As a starting point you have to be on the update to date master branch and be in the root directory of your local git clone. You should also have the same setup on all build machines used.

Update linuxkit/alpine

This step is not necessarily required if the alpine base image has recently been updated, but it is good to pick up any recent bug fixes. Follow the process in alpine-base-update.md

There are several important notes to consider when updating alpine base:

• LK_BRANCH is set to rel_$LK_RELEASE, when cutting a release, for e.g. LK_BRANCH=rel_v0.9
• It not necessarily required to update the alpine base image if it has recently been updated, but it is good to pick up any recent bug fixes. However, you do need to update the tools, packages and tests.
• Releases are a particularly good time to check for updates in wrapped external dependencies, as highlighted in alpine-base-update.md#External Tools

Final preparation steps

• Update AUTHORS by running ./scripts/generate-authors.sh
• Update the VERSION variable in the top-level Makefile
• Create an entry in CHANGELOG.md. Take a look at git log v0.3..HEAD and pick interesting updates (of course adjust v0.3 to the previous version).
• Create a PR with your changes.

Releasing

Once the PR is merged we can do the actual release.

• Update your local git clone to the lastest
• Identify the merge commit for your PR and tag it and push it to the main LinuxKit repository (remote upstream in my case):

git tag $LK_RELEASE master
git push upstream $LK_RELEASE

Then head over to GitHub and look at the Releases tab. You should see the new tag. Edit it:

• Add the changelog message
• Head over to the Circle CI page of the master build (try the Circle CI badge in the top level README.md)
• Download the artefacts and SHA256 sums file.
• Add the downloaded binaries to the release page (drag-and-drop below the editor window)
• Add the sha256 sums to the release notes on the release page

Hit the Publish release button.

This completes the release, but you are not done, one more step is required.

Post release

Create a PR which bumps the version number in the top-level Makefile to $LK_RELEASE+ to make sure that the version reported by linuxkit version gets updated.