From 723386c8639b24522b2a15613de0bd0198ff021d Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 5 Jul 2018 08:49:59 +0100 Subject: [PATCH 1/4] docs: Move Components section next to Versions section Move the Components section next to the Versions section in the Releases document as they are closely related in content. Signed-off-by: James O. D. Hunt --- Releases.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Releases.md b/Releases.md index a7b0a212..08e1ce11 100644 --- a/Releases.md +++ b/Releases.md @@ -1,7 +1,7 @@ * [Introduction](#introduction) * [Versioning](#versioning) -* [Tagging repositories](#tagging-repositories) * [Components](#components) +* [Tagging repositories](#tagging-repositories) * [Release checklist](#release-checklist) * [Release process](#release-process) @@ -34,6 +34,14 @@ Semantic versioning is used since the version number is able to convey clear inf 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. +## 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. + ## 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: @@ -55,14 +63,6 @@ The annotation text must conform to the usual [patch format rules](https://githu - 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). From adccf509cb54ed71174809b0c3ebc8bcba59ecfe Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 5 Jul 2018 08:51:58 +0100 Subject: [PATCH 2/4] docs: Document compatibility of component versions Add new "Component version compatibility" section to the Releases document that explains all component versions must match. Partially fixes #177. Signed-off-by: James O. D. Hunt --- Releases.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Releases.md b/Releases.md index 08e1ce11..2daae1a7 100644 --- a/Releases.md +++ b/Releases.md @@ -1,6 +1,7 @@ * [Introduction](#introduction) * [Versioning](#versioning) * [Components](#components) + * [Component version compatibility](#component-version-compatibility) * [Tagging repositories](#tagging-repositories) * [Release checklist](#release-checklist) * [Release process](#release-process) @@ -42,6 +43,16 @@ This strategy allows diagnostic tools such as `kata-runtime kata-env` to record 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. +### Component version compatibility + +Semantic versioning allows users to determine how a new version of a +particular component relates to the previous version of that component. +However, it is not possible to compare two *different* Kata component +versions, even though all component versions are changed together. + +To ensure compatibility it is necessary to always use components of the same +version. + ## 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: From 48cc415f5f5a741b430672a6c704b2b499a1c4d0 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 5 Jul 2018 09:14:08 +0100 Subject: [PATCH 3/4] docs: Refer to Component version compatibility Update the developer guide and upgrading document to refer to the "Component version compatibility" section of the Releases doc. Fixes #177. Signed-off-by: James O. D. Hunt --- Developer-Guide.md | 17 +++++++++++++++++ Releases.md | 5 ++++- Upgrading.md | 3 ++- 3 files changed, 23 insertions(+), 2 deletions(-) diff --git a/Developer-Guide.md b/Developer-Guide.md index 5d8536a5..8d25f70a 100644 --- a/Developer-Guide.md +++ b/Developer-Guide.md @@ -2,6 +2,7 @@ * [Assumptions](#assumptions) * [Initial setup](#initial-setup) * [Requirements to build individual components](#requirements-to-build-individual-components) +* [Individual component compatibility](#individual-component-compatibility) * [Build and install the Kata Containers runtime](#build-and-install-the-kata-containers-runtime) * [Check hardware requirements](#check-hardware-requirements) * [Configure to use initrd or rootfs image](#configure-to-use-initrd-or-rootfs-image) @@ -75,6 +76,22 @@ You need to install the following to build Kata Containers components: - `make`. - `gcc` (required for building the shim and runtime). +# Individual component compatibility + +Using versions of individual components newer than the last official released +version might result in +[compatibility issues](Releases.md#component-version-compatibility). + +If you have only updated a subset of the Kata components and notice strange +behavior, we recommend you update the remaining components to ensure you are +using the latest versions of all of them. Also, remember to +[create a new image containing the latest agent version](#create-and-install-rootfs-and-initrd-image). + +If you still have compatibility issues after following the previous +instructions, refer to the +[troubleshooting section](#troubleshoot-kata-containers) and +[get in contact with us](https://github.com/kata-containers/community/blob/master/CONTRIBUTING.md#contact). + # Build and install the Kata Containers runtime ``` diff --git a/Releases.md b/Releases.md index 2daae1a7..7e9f8258 100644 --- a/Releases.md +++ b/Releases.md @@ -37,7 +37,10 @@ Semantic versioning is used since the version number is able to convey clear inf ## 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. +A new release results in all Kata components being given a new +[version](#versioning), even if there are no changes 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. diff --git a/Upgrading.md b/Upgrading.md index 7379ff92..e3bd02e4 100644 --- a/Upgrading.md +++ b/Upgrading.md @@ -134,7 +134,8 @@ As shown in the [installation instructions](https://github.com/kata-containers/documentation/blob/master/install), Kata Containers provide binaries for popular distributions in their native packaging formats. This allows Kata Containers to be upgraded using the -standard package management tools for your distribution. +standard package management tools for your distribution and also guarantees +[component version compatibility](Releases.md#component-version-compatibility). # Appendices From b9144b7194fa58210a9a3e8f351c0906030172d6 Mon Sep 17 00:00:00 2001 From: "James O. D. Hunt" Date: Thu, 5 Jul 2018 09:16:17 +0100 Subject: [PATCH 4/4] docs: Add missing title to dev guide Add a title line to the developer guide. Signed-off-by: James O. D. Hunt --- Developer-Guide.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Developer-Guide.md b/Developer-Guide.md index 8d25f70a..6d58f6da 100644 --- a/Developer-Guide.md +++ b/Developer-Guide.md @@ -1,3 +1,5 @@ +# Kata Containers Developer Guide + * [Warning](#warning) * [Assumptions](#assumptions) * [Initial setup](#initial-setup)