Document compatibility of component versions#191
Conversation
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 <james.o.hunt@intel.com>
Add new "Component version compatibility" section to the Releases document that explains all component versions must match. Partially fixes kata-containers#177. Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
jodh-intel
force-pushed
the
component-versions-must-match
branch
from
bc92643 to
ddf3b42
Compare
|
Hi @klynnrif, @intelkevinputnam, @grahamwhaley - ptal. |
grahamwhaley
left a comment
grahamwhaley
left a comment
There was a problem hiding this comment.
A couple of minor things.
|
|
||
| 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 |
There was a problem hiding this comment.
Can you explain or expand on why it is 'not possible to compare...' - it's not quite clear to me here what you are trying to explain.
There was a problem hiding this comment.
Nor me! 😄
I think we're all struggling to really understand what this actually means, but I'm trying to find words, so if you can suggest some based on what follows, I'm all ears! ;)
It's rather difficult to write this. What I'm trying to state is that although we "use" semver for each component, since we require all components to have the same version to be compatible, we require our own... cough.. interpretation of what semver means. It could be argued that semver is implicitly only meant for comparing versions of the same component.
However since we're imposing the extra requirement that all components need to be upgraded in lock-step (all components having the same version), a gRPC protocol change (what would nominally be an "API breakage" for a single component) for example can be handled by a MINOR version number change only (since this detail is invisible to the user assuming they upgrade all components in lock-step).
For example, if the proxy is at version 1.2.0 but the other components are all at 1.1.0, there are no guarantees the system will work.
I'll also probably add words based on @gnawux's comments to the ML (http://lists.katacontainers.io/pipermail/kata-dev/2018-June/000232.html) too.
There was a problem hiding this comment.
Sure, but 1.1.1 and 1.1.0 should be fine. Right?
There was a problem hiding this comment.
@grahamwhaley, @egernst - should we just drop the "Component version compatibility" section entirely then do you think?
There was a problem hiding this comment.
Hi @jodh-intel - I'm prone to put this PR on hold, pretty much just due to this semver related section, until we have the Kata versioning and release flow defined - and then we can reference that.
I believe @jcvenegas is planning a first draft around releases, versioning and backport/lifetimes - let's wait for that.
As such, I'm going to mark this PR as WIP, just to make it clear it is pending an update.
|
|
||
| # Individual component compatibility | ||
|
|
||
| Using newer versions of individual components than the last offical released |
There was a problem hiding this comment.
potential reword, and a typo s/offical/official/
Using versions of individual components newer than the last official released
klynnrif
left a comment
klynnrif
left a comment
There was a problem hiding this comment.
Scrubbed for grammar, structure, and flow. A couple suggestions . Thanks!
| # Individual component compatibility | ||
|
|
||
| Using newer versions of individual components than the last offical released | ||
| version may result in |
| [compatibility issues](Releases.md#component-version-compatibility). | ||
|
|
||
| If you have only updated a subset of the Kata components and notice strange | ||
| behaviour, we recommend you update the remaining components to ensure you are |
|
|
||
| If you have only updated a subset of the Kata components and notice strange | ||
| behaviour, we recommend you update the remaining components to ensure you are | ||
| using the latest versions of all of them. Remember to also [create a new image |
There was a problem hiding this comment.
... Also, remember to [create a new image
| containing the latest agent | ||
| version](#create-and-install-rootfs-and-initrd-image). | ||
|
|
||
| If this still does not work, refer to the |
There was a problem hiding this comment.
Suggested rewrite: If you still have compatibility issues after following the previous instructions, refer to the
|
|
||
| ## 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. |
There was a problem hiding this comment.
Suggested rewrite:
A new release results in all Kata components being given a new version, even if there are no changes to that component since the last version.
Update the developer guide and upgrading document to refer to the "Component version compatibility" section of the Releases doc. Fixes kata-containers#177. Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
Add a title line to the developer guide. Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
jodh-intel
force-pushed
the
component-versions-must-match
branch
from
ddf3b42 to
b9144b7
Compare
|
Thanks @klynnrif - branch updated. |
|
Closing as this is covered by https://github.com/kata-containers/documentation/blob/master/Stable-Branch-Strategy.md. |
tests: allow rootfs build to fail for specific distros
4 participants
Add new "Component version compatibility" section to the Releases document that explains all component versions must match.
Also, 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 james.o.hunt@intel.com