Change version numbering scheme

[miabbott]

We are currently generating the version number using the next major OpenShift release (4.0) and the build ID from Jenkins. This works well as long as we never have to restart the pipeline from scratch.

A proposed way of making the version number more resilient is to retrieve the version number from the previous build (by way of metadata, hopefully) and increment the version.

We can still maintain the 4.0.XXXX format using this method.

[miabbott]

This came out of the discussion in #150 (comment)

[dustymabe]

adding a date to our version in FAH has worked well for us (gives a lot of context). Maybe something we should consider

[miabbott]

So that could look something like 4.0.20180830.4833

Kinda looks long for a version string, but I do like the context it provides.

[ashcrow]

I'm fine with using dates like shown above, but I'm not a big fan of the secondary .. This looks to me like $MAJOR.$MINOR.$PATH.$SOMETHING. The latter item seems to not be inline with semantic versioning for patch. If we need the extra numbers maybe we should look at using it as build metadata.

[ashcrow]

What about $MAJOR.$MINOR.$PATCH+BUILDDATA? Example: 4.0.1+5722.

[dustymabe]

What about $MAJOR.$MINOR.$PATXH+BUILDDATA? Example: 4.0.1+5722.

LGTM.. bonus points if you could put a date in there somewhere

[miabbott]

Glancing at the semver spec, it seems like the date would fall in to the 'build metadata' category. So we would probably want to choose either the build ID or the date.

I guess we could combine the build ID + date, but that would get rather verbose, i.e 4.0.1+5722.20180905 (or 4.0.1+20180905.5722)

[ashcrow]

I'm 👍 with either of date after or before. I like it a little slightly more after but 👍 😄.

[dustymabe]

if getting too verbose we could go with the year/month model other distros are using: 4.0.1+1809.5722. I personally like the full date, though :)

[dustymabe]

I'm +1 with either of date after or before. I like it a little slightly more after but +1 smile.

I prefer the date before because incrementally it makes more sense:

4.0.1+20180905.001
4.0.1+20180905.002

[ashcrow]

I like the full date as well. I'm fine with it coming before.

[lucab]

As a general note, even if we want to adopt the three-dotted format, we are not semver-sioning here. Semver guarantees apply to a clear and precise API:

[...] you first need to declare a public API. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number.

An OS image is an aggregate of multiple projects' API and ABI which are mostly outside of our control and we don't clearly define as a whole.
Thus, we are pretty free to mix build-date, openshift release-tag and incremental OS version label as we prefer, as long as we communicate that there is no semver meaning attached to the resulting string.

[miabbott]

As a general note, even if we want to adopt the three-dotted format, we are not semver-sioning here.

That's fine, I think. I was just referencing the spec as guidelines for creating a reasonable version string.

Thus, we are pretty free to mix build-date, openshift release-tag and incremental OS version label as we prefer, as long as we communicate that there is no semver meaning attached to the resulting string.

Yup, we should definitely communicate this clearly.

[ashcrow]

As a general note, even if we want to adopt the three-dotted format, we are not semver-sioning here.

That's fine, I think. I was just referencing the spec as guidelines for creating a reasonable version string.

👍. True we would not be strict semver but I agree with @miabbott that's it's a good guideline.

If we don't have any strong disenters to this proposal by this Friday noon EDT let's accept the version pattern.

[lucab]

It is a good guideline, counterpoint is that if you have something that quacks like a semver then people assume it indeed is semver and get very angry about breakages (see docker 1.x series and yy.mm renumbering).

[ashcrow]

@lucab fair point. Do you have a counter proposal or do you think we should specifically avoid semver?

[wking]

What's the 4.0 bit about? Do we have different RHCOS channels targeting different OpenShift channels? If not, can we just tag 2018-09-19.1234?

[cgwalters]

What's the 4.0 bit about? Do we have different RHCOS channels targeting different OpenShift channels?

No, not today. I guess the 4.0 is perhaps redundant. One thing that is critical though is whether the host is maipo or ootpa. But...that will hopefully soon be reflected in the custom origin from the oscontainer.

[lucab]

@ashcrow I didn't want to bikeshed or unilaterally drag this. If people are ok with the semver-like approach go for it, I was only detailing the psychological effect (with real-word past cases).

Not actively proposing any of those, but looking at other projects, confusion can be avoided by using a serial counter (systemd), a date based approach (ostree), always bumping the most-significant field (CL), or just using different separators other than dots.

[ashcrow]

@lucab understood. Thanks!

[cgwalters]

How about 4.7.X for maipo and 4.8.X for ootpa? Or if we wanted to avoid appearing like it's semver, just 47.X and 48.X. Or even more clearly less semver, 47-X and 48-X. Then the value of X could be a serial number (week number + serial), date stamp, whatever.

[ashcrow]

I'm not a big fan of 4.7.X or 4.8.X as I think it may stomp on mapping to broader releases. 47.X would work better. If we want to track maipo and ootpa we could instead do 4.0.1+20180905.7.002. IE:

$BROADERRELEASE.$BROADERRELEASE.$OURPATCH+$DATE.$UPSTREAMRELEASE.$BUILD

[cgwalters]

as I think it may stomp on mapping to broader releases.

Can you elaborate on that? Releases of...OpenShift? My instinct now says that...let's try not to encode specific details in our version number of the kubelet/cri-o that we maintain. The whole cluster state is also a function of the versions of the containers.

47.X would work better.

Ok yeah I definitely lean that way too. (And not having $DATE for now personally)

[cgwalters]

openshift/redhat-release-coreos#12

[jlebon]

Not to add more wood to the bikeshed bonfire 🔥, but 47/48 seems limiting to me. Thinking in terms of how often we'll refer to these versions, we'll stop caring about 47/48 and more about the X. It just feels odd to have a leading number that won't really change that much. If the idea is to

1. somehow incorporate the major OKD version, and
2. somehow incorporate whether it's maipo or ootpa, but
3. still signal no guarantees

Then I like the idea of CL where we keep bumping major. So e.g., something like 183.7.4-$BUILD, where 183 is e.g. days since something. It looks like semver, but that's fine, we're bumping major everyday anyway.

[ashcrow]

Let's continue and try to finish this off.

If we do not have a consensus by Oct 5th noon EDT we will run with the version scheme with the most acceptance

[ashcrow]

/assign @ashcrow

[dustymabe]

my vote is still for something like 4.0.1+20180905.001. another alternative for representing the openshift version would be to crunch all of openshift versioning into the first number (e.g. 401.), which would give us more room to use the other fields. 401.7.20180905+001. So OCP 4.0.1, EL7, built on $day and then number of build during that day.

@ashcrow do you want to summarize the different options and maybe we could vote ?

[ashcrow]

Sure!

Semver like

1. $MAJOR.$MINOR.$PATCH+$DATE.$BUILD Example: 4.0.1+20180905.001
2. $OCPMAJORMINORPATH.$RHELMAJOR.$DATE+$BUILD: Example: 401.7.20180905+001
3. $OCPMAJOR.$RHELMAJOR.$BUILD: Example 4.7.1

Alternative

4. $OCPMAJOR$RHELMAJOR.$BUILD: Example 47.1
5. $DAYSSINCEFIRSTRELEASE.$RHELMAJOR.$OCPMAJOR-$BUILD: Example 52.7.4-1

edited by @dustymabe to include numbers so they can be referenced in future coments.

[ashcrow]

Can you elaborate on that? Releases of...OpenShift? My instinct now says that...let's try not to encode specific details in our version number of the kubelet/cri-o that we maintain. The whole cluster state is also a function of the versions of the containers.

My concern is if there is a 4.7 release of Openshift and we go out the door with a 4.7.x things could become confusing trying to match up RHCOS and OCP from a docs/user/developer POV. Of course we'd know how to parse, traverse, and match the versions but it would not be obvious or near obvious from the outside.

[cgwalters]

It just feels odd to have a leading number that won't really change that much.

There are also quite a lot of projects with a leading major that's been the same for years; Linux kernel to name one prominent one. And, for users going from 47 to 48 it'll be a big change. But then indeed we'll hopefully be on 48 for quite a while. But even then, after say 2-3 years, I wouldn't be surprised if one of the components changed.

[ashcrow]

Folks: Please respond to this issue with your favorite scheme as proposed.

Reminder: If we do not have a consensus by Oct 5th noon EDT we will run with the version scheme with the most acceptance

[dustymabe]

Top choice #1. Close 2nd is #2.

[miabbott]

Top choice #1. Close 2nd is #2.

Same here

[cgwalters]

I don't understand under what operations the MINOR and PATCH would be rev'd versus BUILD. How would that translate to our tooling? And I still don't like having a full date in the version, it's really verbose.

Not to mention that AFAICS #1 doesn't have any obvious way to distinguish between maipo/ootpa, but that to me is quite important.

Those questions are why I am proposing (and voting for) #4 - and have already made implementation moves towards it.

[ashcrow]

I also prefer 1 and 2.

I think noting maipo versus ootpa is a nice to have, but since ootpa is where we are going I don't see a hard requirement to call it out.

[ashcrow]

@cgwalters proposal 2 does separate maipo/oopta through $RHELMAJOR

[cgwalters]

@cgwalters proposal 2 does separate maipo/oopta through $RHELMAJOR

OK but for the people including #1 in their vote - do you think $RHELMAJOR isn't important, or that we would distinguish between these in some other way? If the latter, once we move to pivoting the images, the oscontainer name will be in the rpm-ostree status but still, it's...kind of important right?

[cgwalters]

(Or if the answer is "I didn't consider maipo vs ootpa", please do and edit your vote)

[miabbott]

I think noting maipo versus ootpa is a nice to have, but since ootpa is where we are going I don't see a hard requirement to call it out.

I think this is where my thinking was. But if @cgwalters feels that the maipo/oopta distinction is worth calling out, I'll edit my response to be #2 as my preference.

[dustymabe]

OK but for the people including #1 in their vote - do you think $RHELMAJOR isn't important,

A lot of the discussion that we had about this was before we (I?) even considered $RHELMAJOR much at all. So I think it was a combination of hadn't considered it much and it's not that important. My thinking was that we could easily derive $RHELMAJOR from the OCP version since there should be a single clear OCP version where we cut over. i.e. there would never be a 4.0.1 based on maipo AND a 4.0.1 based on ootpa.

That being said, #2 was a close 2nd in my vote and includes the $RHELMAJOR, so if you feel strongly I can lean towards that.

[cgwalters]

My thinking was that we could easily derive $RHELMAJOR from the OCP version since there should be a single clear OCP version where we cut over. i.e. there would never be a 4.0.1 based on maipo AND a 4.0.1 based on ootpa.

I would like to offer some customers the option of trying out newer content. I can't say for sure whether or not that would really happen. But even if it didn't - during development I am doubtful there's going to be some sort of hard cutover, and we want it to be immediately obvious which OS major version people are testing.

And even all of that aside, it still feels extremely weird to me to have the idea that the whole OS could change in a huge way from 4.0 to 4.1, but then maybe not much at all from 4.1 to 4.2 - given that the version number we're talking about here is for our builds which are definitely operating system-focused (as opposed to higher level OpenShift versions).

[ashcrow]

Based on the conversation it looks like the best consensus we have is to go with option 2:

$OCPMAJORMINORPATH.$RHELMAJOR.$DATE+$BUILD: Example: 401.7.20180905+001

I'll create a new issue to implement this.