stable: initial stable-branching documentation by egernst · Pull Request #238 · kata-containers/documentation

egernst · 2018-08-31T23:42:26Z

It is expected that this document will change over time. This
represents an initial starting point as we create and release
our stable branches.

Fixes: #237

Requirements for this document:

- what stable branches are.
- how to create them.
- how to populate them.
-how to test them.

egernst · 2018-08-31T23:44:42Z

Please help review.

I think as part of our stable release process, we should also consider releasing from master an RC branch (when there are deltas on master versus stable). This will allow earlier access to features which are targetting the next MINOR release update. We hadn't really discussed this before, but I think we should consider adding it to this document? Feedback please?

If you have considerable edit suggestions, I'd be happy to see a commit applied / submitted to my branch. I don't have bandwidth to do many many piecemeal edits :)

PTAL @bergwolf @gnawux @jodh-intel @grahamwhaley

gnawux · 2018-09-01T17:55:17Z

+Stable: 1.2.2
+```
+
+Note, the 1.1.3 branch will still exist, but under current plans it would not be maintained further. 


[minor] should be 1.1.x branch

gnawux · 2018-09-01T17:59:15Z

Thanks, Eric. Overall I think it's OK and identical to what we discussed in the weekly meeting.
will look into detail later.

marcov

The doc is quite clear for me, it looks good as a starting point.

marcov · 2018-09-03T09:23:26Z

+Consider the following initial state:
+Master 1.3.rc0
+Stable 1.2.0
+Stable 1.1.2


I would surround this with ``` to match the rest of the doc

marcov · 2018-09-03T10:08:52Z

+The test repository will also be forked to create stable branches based off of master. Full CI
+will run on each stable and master PR, using its respective tests repository branch.
+
+### An alternative method for CI testing: suggestiong to revisit:


suggestiong to revisit: to be dropped?

marcov · 2018-09-03T10:08:55Z

+
+Development will occur against the master branch and applicable code commits should also be submitted
+against the stable branch. Some guidelines:
+-Only bug and security fixes which do not introduce inter-component dependencies are


fix the list formatting

marcov · 2018-09-03T10:09:00Z

+```
+Master: 1.3.0
+Stable: 1.3.0
+Stable: 1.2.2


Shouldn't the older branch continue be Stable: 1.2.1?

marcov · 2018-09-03T10:09:04Z

+Consider the following initial state:
+Master 1.3.rc0
+Stable 1.2.0
+Stable 1.1.2


What about having a unique name given to the 2 Stable to help disambiguate? Something like Current stable and Previous stable.

jodh-intel · 2018-09-03T10:16:24Z

+
+# Overview
+
+As detailed in the release documentation, the Kata Containers project makes use of


We need a link to that release documentation here.

jodh-intel · 2018-09-03T10:17:09Z

+# Overview
+
+As detailed in the release documentation, the Kata Containers project makes use of
+semantic versioning.  A release version is described by MAJOR.MINOR.PATCH.  Early in


This duplicates: https://github.com/kata-containers/documentation/blob/master/Releases.md#versioning.

jodh-intel · 2018-09-03T10:17:36Z

+
+As detailed in the release documentation, 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 will require a minor version change


s/version change/version changes/

jodh-intel · 2018-09-03T10:18:26Z

+
+## Branch Management
+Kata Containers will maintain two stable release branches in addition to the master branch.
+Once a new MAJOR or MINOR release is created off of master, a new stable branch will be created for


I'd say "created from master" rather than "created off of master" as it read a little better. Same comment for "off of" below...

jodh-intel · 2018-09-03T10:20:36Z

+## Branch Management
+Kata Containers will maintain two stable release branches in addition to the master branch.
+Once a new MAJOR or MINOR release is created off of master, a new stable branch will be created for
+the prior MAJOR or MINOR release and the older stable branch will no longer be maintained.


What happens to that branch?:

Is it deleted or somehow marked "unmaintained"?

What about references to the branch "elsewhere"?

What about OBS packages / branches for this branch release?

What about users running on that release? We need to explain how they can:

upgrade the the next stable release

stay on that release (but with big fat warnings about (lack of) security updates, etc).

jodh-intel · 2018-09-03T10:38:32Z

+### Patch releases
+
+Releases will be made on a weekly cadence for both stable branches for patch releases. If there
+are no changes across all the repositories, no release will be created. If a release is being made,


We need to ensure users are always aware of new releases. As such, I think we should specify in this doc:

How we announce releases (we should always send a mail to the public ML).

That we will always announce that a release is not going to be made for a particular week due to lack of changes.

should this be part of the releases guide?

The first bullet is covered in https://github.com/kata-containers/documentation/blob/master/Release-Checklist.md but the second doesn't really "fit" that document since the doc assumes a release will be created.

jodh-intel · 2018-09-03T10:39:23Z

+## Minor releases
+
+###  Frequency
+Minor releases should be less frequent, though are currently running on a six week cadence. As the


"should"? Should that be "are"? Also, would be worth being explicit about why they are less frequent.

jodh-intel · 2018-09-03T10:42:33Z

+Kata Containers code base matures it is expected this will become a much longer duration.
+
+### Compatibility
+Kata will guarantee compatibility between components that are within one minor release of each other. 


Please see #191 (and feel to use anything in there in this PR (as #191 can be superceded by this PR).

jodh-intel · 2018-09-03T10:42:47Z

+the guest (hypervisor, rootfs and agent).  For example, consider a cluster with a long-running
+deployment, workload-never-dies, all on kata version 1.1.3 components. If the operator updates
+the Kata components to the next new minor release (1.2.0), we need to guarantee that the 1.2.0
+runtime can still communicate with 1.1.3 agent within workload-never-dies.


Again, some tabular examples would make this clearer I think.

jodh-intel · 2018-09-03T10:44:12Z

+the Kata components to the next new minor release (1.2.0), we need to guarantee that the 1.2.0
+runtime can still communicate with 1.1.3 agent within workload-never-dies.
+
+Handling live-update is out of the scope of this document, but will need to be supported so we can


I'd change this to just:

Handling live-update is out of the scope of this document. See kata-containers/runtime#492 for details.

egernst · 2018-09-05T04:07:05Z

@WeiZhang555 @jon PTAL?

marcov · 2018-09-05T10:57:36Z

+### New bug fix introduced
+
+A bug fix is submitted against the runtime which does not introduce new inter-component dependencies.
+This fix will be applied to both the master and stable branch.


I would add here something like (reword as you prefer):

In this case there is no need to create a new stable branch

marcov · 2018-09-05T11:06:52Z

+
+### New release made feature or change which  adds new inter-component dependency
+
+A new feature is introduced which adds a new inter-component dependency.


I would add here something like (reword as you prefer):

In this case a new stable branch is created (stable-1.3) starting from master and the older stable branch (stable-1.1) is dropped from maintenance.

marcov · 2018-09-05T11:07:00Z

+| `master` | `1.3.rc1` | `1.3.0` |
+| `stable-1.3` | `1.2.1` | `1.3.0` |
+| `stable-1.2` | `1.1.3` | `1.2.2` |
+


What about using this table? I took a while to figure out what was going on above.

Branch Original version New version

master 1.3.rc1 1.3.0

stable-1.3 N/A 1.3.0

stable-1.2 1.2.1 1.2.2

stable-1.1 1.1.3 (unmaintained)

marcov · 2018-09-05T11:08:44Z

+ (2) Once a PR is created against master which meets requirement of (1), a comparable one
+ should also be submitted against stable. It is the responsibility of the submitter to apply
+ their pull request against stable, and it is the responsibility of the
+ reviewers to help identify stable-candidate pull requests.


s/stable branch/stable branches/

egernst · 2018-09-05T23:03:13Z

@klynnrif @intelkevinputnam - I think we're getting close enough that your review will be helpful and appreciated. PTAL?

jodh-intel · 2018-09-06T07:10:32Z

+
+| Branch | Original version | New version |
+|--|--|--|
+| `master` | `1.3.rc0` | `1.3.rc1` |


The original version for master here and below are not semver. See kata-containers/shim#109.

ACK - hyphen on the way...

klynnrif

Scrubbed for grammar, structure, and flow. Rewrites suggested in large part to stay in an active voice. Thanks!

klynnrif · 2018-09-06T18:24:24Z

+
+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 will require


... Early in the project we will introduce many new features, which require

klynnrif · 2018-09-06T18:28:33Z

+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 will require
+minor version changes as well as bug fixes.  To facilitate a stable user environment, Kata will
+begin to provide stable branch based releases as well as a master branch release.


begin to provide stable branch-based releases and a master branch release.

klynnrif · 2018-09-06T18:30:21Z

+
+## Stable branch patch criteria
+
+No new features should be introduced to stable branches.  The intention is to limit risk to users,


... This is intended to limit the risk to users,

klynnrif · 2018-09-06T18:32:17Z

+
+## Branch Management
+Kata Containers will maintain two stable release branches in addition to the master branch.
+Once a new MAJOR or MINOR release is created from master, a new stable branch will be created for


Lines 18-19 suggested rewrite ... a new stable branch is created for the prior MAJOR or MINOR release and the older stable branch is no longer maintained.

klynnrif · 2018-09-06T18:32:49Z

+Once a new MAJOR or MINOR release is created from master, a new stable branch will be created for
+the prior MAJOR or MINOR release and the older stable branch will no longer be maintained.
+
+A couple of examples are provided to help clarify this process.


A couple of examples follow to help clarify this process.

klynnrif · 2018-09-06T18:43:16Z

+
+### An alternative method for CI testing:
+
+Ideally the continuous integration infrastructure will run the same test suite on both master


Ideally, the continuous integration infrastructure runs the same test suite on both master

klynnrif · 2018-09-06T18:44:02Z

+Ideally the continuous integration infrastructure will run the same test suite on both master
+and the stable branches.  When tests are modified or new feature tests are introduced, explicit
+logic should exist within the testing CI to make sure only applicable tests are executed against
+stable and master. This is not in place today, but should be considered in the longer term.


... While this is not in place currently, it should be considered in the long term.

klynnrif · 2018-09-06T18:44:27Z

+
+### Patch releases
+
+Releases will be made on a weekly cadence for patch releases, which will include a GitHub release as


Lines 80-85 suggested rewrite to be active:

Releases are made on a weekly cadence for patch releases, which include a GitHub release as well as binary packages. These patch releases are made for both stable branches, and a 'release candidate' for the next MAJOR or MINOR are created from master. If there are no changes across all the repositories, no release is created and an announcement is made on the developer mailing list to highlight this. If a release is being made, each repository is tagged for this release, regardless of whether changes are introduced.

klynnrif · 2018-09-06T18:48:25Z

+a much longer duration.
+
+### Compatibility
+Kata will guarantee compatibility between components that are within one minor release of each other. 


Kata guarantees compatibility between components that are within on minor release of each other.

klynnrif · 2018-09-06T18:53:13Z

+### Compatibility
+Kata will guarantee compatibility between components that are within one minor release of each other. 
+
+This is especially critical for dependencies which cross between host (runtime, shim, proxy) and


Lines 97-101 suggested rewrite:

This is critical for dependencies that cross between host (runtime, shim, and proxy) and the guest (hypervisor, rootfs, and agent). For example, consider a cluster with a long-running deployment and workload-never-dies on kata version 1.1.3 components. If the operator updates the Kata components to the next new minor release (i.e. 1.2.0), we need to guarantee that the 1.2.0 runtime still communicates with the 1.1.3 agent within workload-never-dies.

egernst · 2018-09-10T20:40:29Z

updated. ptal.

jodh-intel · 2018-09-11T06:21:17Z

@@ -0,0 +1,103 @@
+Branch and release maintenance for Kata Containers project


s/for Kata/for the Kata/ ? Missing period.

jodh-intel · 2018-09-11T06:25:25Z

+
+Releases are made on a weekly cadence for patch releases, which include a GitHub release as
+well as binary packages. These patch releases are made for both stable branches, and a 'release candidate'
+for the next `MAJOR` or `MINOR` are created from master. If there are no changes across all the repositories, no


s/are created/is created/

jodh-intel · 2018-09-11T06:26:19Z

+the Kata components to the next new minor release (i.e. 1.2.0), we need to guarantee that the 1.2.0
+runtime still communicates with 1.1.3 agent within workload-never-dies.
+
+Handling live-update is out of the scope of this document. See kata-containers/runtime#492 for details.


Can you change that issue reference for a full URL to make it clickable?

jodh-intel · 2018-09-11T06:30:24Z

+## Branch Management
+Kata Containers will maintain two stable release branches in addition to the master branch.
+Once a new MAJOR or MINOR release is created from master, a new stable branch is created for
+the prior MAJOR or MINOR release and the older stable branch is no longer maintained.


I think we need to explain the options for users currently using the older stable branch:

How do they know the branch has become EOL? (ML posting)

How do they upgrade to the newer stable branch? (automatic via OBS distro-packaged components?)

We should explain how users can establish the version they are currently running (by running kata-runtime kata-env).

Addressed the easy parts of this feedback. I think the end-user OBS usage is still in flux, and I am not sure if it should be included in this document or an end-user installation document.

jodh-intel · 2018-09-11T06:32:33Z

+
+## Continuous Integration Testing
+
+The test repository will also be forked to create stable branches from master. Full CI


I'm not sure if we have all agreed to this yet, but I think we should also fork the documentation repo: consider how useful that would be not only for release-specific installation guides, but also:

release-specific limitations docs

kinda essential ;)

release-specific developer guide

very useful as we don't want to have to say things in there like,

if you are running a release >= 1.2.3 and < 9.2.6, run these commands...
However, if you are running release 3.99.6, run the following commands instead.

with a fork tied to the release in question, that problem goes away.

WeiZhang555 · 2018-09-12T08:23:54Z

Content and policy look good to me, I'm not good at grammar so leave this part to @jodh-intel and @klynnrif

egernst · 2018-09-12T15:07:57Z

@jodh-intel - are you okay with resolving #238 (comment) in a follow on issue/PR?

I would like to get what's agreed upon and done today in as a starting point, and think we can and will need to improve this document over time as we change policies.

Issue: #246

jodh-intel · 2018-09-12T15:20:19Z

@egernst - sure - wfm.

lgtm

egernst · 2018-09-12T16:42:40Z

@klynnrif - addressed your feedback - can you PTAL?

egernst · 2018-09-13T19:17:19Z

@intelkevinputnam can you PTAL?

grahamwhaley · 2018-09-14T10:02:31Z

+
+| Branch | Original version | New version |
+|--|--|--|
+| `master` | `1.3.0-rc1` | `1.3.0` |


We might need to clarify, check or document how this master move from rc1 to no-extension then relates to 1.4.0. At this specific point in this flow we have two branches with 1.3.0, which is OK as they are on the identical commit I believe - but, what we don't explain is when we add the next commit to the master branch, how or will that go to 1.4.0 or 1.4.0-rc1. I suspect the master should have maybe moved to 1.4.0 at this point? And then we need to clarify where the -rcn extentions come into play.

ACK - updated.

grahamwhaley · 2018-09-14T10:04:21Z

+
+Development will occur against the master branch and applicable code commits should also be submitted
+against the stable branches. Some guidelines:
+ (1) Only bug and security fixes which do not introduce inter-component dependencies are


maybe this (1), (2) section should be a markdown numbered list?

+1. I think I may have noted that in a preview review too.

klynnrif

lgtm - apologies for the delay.

jodh-intel · 2018-09-18T07:15:40Z

Although this is now mergeable, there are still a handful of unresolved comments (quick to fix :), so let's wait for them... ;)

It is expected that this document will change over time. This represents an initial starting point as we create and release our stable branches. Fixes: kata-containers#237 Signed-off-by: Eric Ernst <eric.ernst@intel.com>

egernst · 2018-09-18T14:25:50Z

@jodh-intel - updated (finally) - sorry those comments were not addressed before!

jodh-intel · 2018-09-18T14:31:36Z

Thanks @egernst - let's do this thing...!

euleros mirrors are down almost all time, don't fail if euleros rootfs or image can't be generated. fixes kata-containers#238 Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com> Signed-off-by: Julio Montes <julio.montes@intel.com>

egernst added the review label Aug 31, 2018

gnawux reviewed Sep 1, 2018

View reviewed changes

marcov reviewed Sep 3, 2018

View reviewed changes

marcov mentioned this pull request Sep 3, 2018

Update release documentation for stable branch releases #237

Closed

6 tasks

jodh-intel reviewed Sep 3, 2018

View reviewed changes

egernst force-pushed the stable-documentation branch from 1aa4e33 to 14e03bf Compare September 4, 2018 22:56

marcov reviewed Sep 5, 2018

View reviewed changes

egernst force-pushed the stable-documentation branch 2 times, most recently from c0acaff to a9e5e8e Compare September 5, 2018 23:02

jodh-intel reviewed Sep 6, 2018

View reviewed changes

egernst force-pushed the stable-documentation branch from a9e5e8e to c900ddb Compare September 6, 2018 17:36

klynnrif suggested changes Sep 6, 2018

View reviewed changes

egernst force-pushed the stable-documentation branch from c900ddb to 203f172 Compare September 10, 2018 20:40

jodh-intel reviewed Sep 11, 2018

View reviewed changes

egernst mentioned this pull request Sep 12, 2018

stable: consider forking documentation repository #246

Closed

egernst force-pushed the stable-documentation branch from 203f172 to 04cece1 Compare September 12, 2018 15:16

egernst force-pushed the stable-documentation branch from 04cece1 to 3233274 Compare September 12, 2018 16:45

grahamwhaley reviewed Sep 14, 2018

View reviewed changes

klynnrif approved these changes Sep 17, 2018

View reviewed changes

egernst force-pushed the stable-documentation branch 2 times, most recently from d0b933a to 355048c Compare September 18, 2018 14:22

stable: initial stable-branching documentation

2594c90

It is expected that this document will change over time. This represents an initial starting point as we create and release our stable branches. Fixes: kata-containers#237 Signed-off-by: Eric Ernst <eric.ernst@intel.com>

egernst force-pushed the stable-documentation branch from 355048c to 2594c90 Compare September 18, 2018 14:25

jodh-intel merged commit 13aed3a into kata-containers:master Sep 18, 2018


		# Overview

		As detailed in the release documentation, the Kata Containers project makes use of


		### New release made feature or change which adds new inter-component dependency

		A new feature is introduced which adds a new inter-component dependency.

Branch	Original version	New version
`master`	`1.3.rc1`	`1.3.0`
`stable-1.3`	N/A	`1.3.0`
`stable-1.2`	`1.2.1`	`1.2.2`
`stable-1.1`	`1.1.3`	(unmaintained)


		## Stable branch patch criteria

		No new features should be introduced to stable branches. The intention is to limit risk to users,


		### An alternative method for CI testing:

		Ideally the continuous integration infrastructure will run the same test suite on both master


		### Patch releases

		Releases will be made on a weekly cadence for patch releases, which will include a GitHub release as

		@@ -0,0 +1,103 @@
		Branch and release maintenance for Kata Containers project


		## Continuous Integration Testing

		The test repository will also be forked to create stable branches from master. Full CI

Conversation

egernst commented Aug 31, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

egernst commented Aug 31, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gnawux commented Sep 1, 2018

Uh oh!

marcov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

egernst commented Sep 5, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marcov Sep 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

egernst commented Sep 5, 2018

Uh oh!

egernst commented Aug 31, 2018 •

edited

Loading

egernst commented Aug 31, 2018 •

edited

Loading

marcov Sep 5, 2018 •

edited

Loading